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Chapter 1 


Messaging Framework API 


1.1 References 


[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 
[2] Messaging API, Version 1.0, LiMo Foundation, | February 2008 


1.2 Overview 


The LiMo Messaging Framework provides services for applications to send, receive, parse and assemble 
messages over arbitrary message delivery mechanisms such as MMS, SMS, email, and i-mode message. 
The messaging services consist of common functions and sets of message delivery service-specific func- 
tions. Also, the Messaging Framework provides a collection of data structures to implement the services. 


The Messaging Framework is built on a modular, plug-in architecture for the flexibility and extendability of 
the messaging system. The functional logic for a particular service type resides in a plug-in module, not in 
the Messaging Framework, allowing the messaging system to be customized for a particular use-case. The 
Messaging Framework provides the interface and protocols for plug-ins and applications to communicate 
with each other in a consistent manner, thus providing simplified messaging for applications. 


In addition, the Messaging Framework also manages the plug-ins, providing plug-in discovery and initial- 
ization as well as other full life-cycle management. Therefore, plug-ins are also required to provide man- 
agerial functions and structures to cooperate with the Framework. For more information, see Overview of 
the LiMo Messaging Plug-ins for more information. 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


Messaging Framework API 


1.5 Plug-in Extension Point Interface 


None 


1.6 Other Interfaces 


None 


1.7 Other Notes 


None 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


Chapter 2 


Data Structure Index 


2.1 Data Structures 


Here are the data structures with brief descriptions: 


_MSG_ACCOUNT_ID_LIST_S (Represents an account id list) ................. 
_MSG_ACCOUNT_S (Represents an account) ...... o... o... .... ee ees 
_MSG_CONTACT_LIST_S (Represents a contact list ) . ........... o... o... .. 
_MSG_CONTACT_S (Represents a contact) ....... o... o... eee eee eee 
MSG_FILTER_ID_LIST_S (Represents a filter id list) ..................... 
MSG_FILTER_LIST_S (Represents a filter list ) .......... o... o... ....... 
_MSG_FILTER_S (Represents a filter ) .......... o... e... . . . . eee eee 
_MSG_FOLDER_ID_LIST_S (Represents a folder id list) .................... 
_MSG_FOLDER_S (Represents a folder) .......... o... e... e... . . +... 0. 
_MSG_FW_STORAGE_S (Represents a framework storage plugin handle) ........... 
_MSG_MESSAGE_ID_LIST_S (Represents a message id list). ................. 
_MSG_MESSAGE_REQUEST_S (Represents a request that will be sent to messaging frame- 
WOK ) saie ia a da Re we E ra Se ewe Ew aaa 4 
_MSG_MESSAGE_S (Represents a Message). ............. . +... ee es 
_MSG_MESSAGE_STATUS_S (Represents a message status). .......... o... . .. 
_MSG_MESSAGE_TYPE_LIST_S (Represents a message types list) .............. 
_MSG_MESSAGE_TYPE_S (Represents a message type) . . . ooo e 
_MSG_PLG_STORAGE_S (Represents a message storage plugin handle). ........... 
_MSG_PLUGIN_FILTER_MANAGER S (Represents a filter manager). ............ 
_MSG_PLUGIN_TRANSPORT_S (Represents a transport plugin handle). ........... 
MSG_QUERY_ID_LIST_S (Represents a query Id list). .............. o... .. 
MSG_QUERY_LIST_S (Represents a query list) ............ o... ...... ... 
_MSG_QUERY_S (Represents a query rule ) ........... o... . e... e. +... . .. 
MSG_SORT_RULE_S (Represents a sort rule ) ............. o... +... eee 
MSG_SORT_TYPE_LIST_S (Represents a sort type list) .......... o... o... ... 
_MSG_STORAGE_ID_LIST_S (Represents a storage id list) .................. 
_MSG_STRING_S (Represents a string) ............. .... eee eee ee eee 
_MSG_TRANSPORT_LISTENER_S (Represents a transport listener handle) .......... 


Data Structure Index 
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Chapter 3 


File Index 


3.1 File List 


Here is a list of all files with brief descriptions: 


ComponentOverview.h (Component Programming Interface Overview Header Template for 

Doxygen) 2 sei eee ea a ad ia A 
Msg_Framework_Storage_Interface.h (Defines the interfaces that framework storage plugin 
MUST implement:) +. ca 28% ad de eae ee ds Sa she ead 
Msg_Mapi_Account.h (Defines the account structure) ...... o... o... e... . . .. 
Msg_Mapi_Contact.h (Defines the contact structure) ....... o... o... e. +... . .. 
Msg_Mapi_FilterRule.h (Defines the filter related structures). .................. 
Msg_Mapi_Folder.h (Defines the folder related structures) ........ o... o... .. .. 
Msg_Mapi_Message.h (Defines the message structure) ...... o... o... e... . . .. 
Msg_Mapi_Message_Request.h (Defines the message request structure ) . ............ 
Msg_Mapi_Message_Status.h (Defines the message status Structure). .............. 
Msg_Mapi_QueryRule.h (Defines the query related structure) ........ o... o... .. 
Msg_Mapi_Types.h (Defines general types) ........ o... ....... e... «o. 
Msg_Plugin_Filter_Interface.h (Defines the filter interfaces that filter plugin MUST implement ) 
Msg_ Plugin Storage_Interface.h (Defines the interfaces that message storage plugin MUST im- 
plement) bisp 6b ee MO da Be oe ee a BE Bee AY SO 
Msg_Plugin_Transport_Interface.h (Defines the transport interfaces that transport plugin MUST 
plement y. soa ic a Bl es QA Ate Boke. OA RAGA ER fon cc 
Msg_Plugin_Types.h (Defines general types for plugins) ........ o... o... +... . .. 


gi 
104 


File Index 
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Chapter 4 


Page Index 


4.1 Related Pages 


Here is a list of all related documentation pages: 


Overview of the LiMo Messaging Plug-ins ...... o... o... e... e... 
Sequence Charts for the LiMo Messaging API ........... o... o... .. e... ..- 


Page Index 
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Chapter 5 


Data Structure Documentation 


5.1 MSG ACCOUNT_ID_LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.1.1 Detailed Description 


Represents an account id list. 


Data Fields 


e intiCount 
e MSG_ACCOUNT_ID_T x accountlds 


5.1.2 Field Documentation 
5.1.2.1 int MSG ACCOUNT ID _LIST_S::iCount 


The count of message ids 


5.1.2.2 MSG ACCOUNT_ID_T« MSG ACCOUNT_ID_LIST_S::accountIds 


The pointer to the account id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.22 MSG ACCOUNT S Struct Reference 


#include <Msg_Mapi_Account.h> 


5.2.1 Detailed Description 


Represents an account. 


All the fields except for pExData contain common information for an account. The field pExData points 
to the user customized structure. This customized structure should be used by application and message 
storage plugin. 


For the more detailed information of account, please refer to OverviewStructureAccount. This structure is 
extendable. Please refer to Extendability (see Messaging API [2]) . 


Data Fields 


MSG_ACCOUNT_ID_T accountld 
MSG_STRING_S accountName 
MSG_MESSAGE_TYPE_S msgType 
MSG_FOLDER_ID_T rootFolderld 
MSG_STORAGE_ID_T storageld 
MSG_STORAGE_ID_T defaultMsgStorageld 
size_textDataSize 


void x pExtData 


5.2.2 Field Documentation 
5.2.2.1 MSG ACCOUNT_ID_T MSG ACCOUNT S::accountId 


Indicates the unique account index. 


5.2.2.2 MSG STRING S MSG ACCOUNT S::accountName 


Indicates the display name for this account. 


5.2.2.3 MSG MESSAGE TYPE_S MSG ACCOUNT _S::msgType 


Indicates the message type of an account, such as SMS, MMS, EMAIL and i-mode message. 


5.2.2.4 MSG FOLDER ID_T MSG ACCOUNT S::rootFolderId 


Indicates the root folder which is assigned to this account. 


5.2.2.5 MSG STORAGE ID_T_MSG_ ACCOUNT _S::storageld 


Indicates the storage id in which this account (metadata and extension data) is stored. 
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5.2.2.6 MSG STORAGE ID_T_MSG_ ACCOUNT _S::defaultMsgStorageld 


Indicates default storage id for the message of this account 


5.2.2.7 size_t MSG ACCOUNT S::extDataSize 


Indicates the size of p] 


ExtData 


5.2.2.8 voids MSG_ACCOUNT_S::pExtData 


Used to add account extension data. For example, the mail box setting of Email account. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Acc 


ount.h 
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5.33 MSG CONTACT LIST_S Struct Reference 


#include <Msg_Mapi_Contact.h> 


5.3.1 Detailed Description 


Represents a contact list. 


Data Fields 


e intiCount 
e MSG_CONTACT_S x pContacts 


5.3.2 Field Documentation 
5.3.2.1 int_MSG_CONTACT_LIST_S::¡Count 


Indicates the number of the contacts in the list. 


5.3.2.2 MSG_CONTACT_S*_MSG_CONTACT_LIST_S::pContacts 


The pointer to the contact list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Contact.h 
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54 MSG CONTACT 5S Struct Reference 


#include <Msg_Mapi_Contact.h> 


5.4.1 Detailed Description 


Represents a contact. 


This structure includes the contact basic information. It can present various contact type such as telephone 
number, email address and so on. 


This structure is extendable. Please refer to Extendability (see Messaging API [2]) . 


Data Fields 


e MSG_CONTACT_TYPE_T contactType 
e unsigned char x contactVal 

e MSG_STRING_S contactName 

e size_t extDataSize 

e void x pExtData 


5.4.2 Field Documentation 


5.4.2.1 MSG CONTACT_TYPE_T MSG CONTACT _S::contactType 


Indicates contact type. 

Two types are predefined: 

MSG_CONTACT_TYPE_EMAIL is for email address like abc@example.com 
MSG_CONTACT_TYPE_PLMN is for phone number like +10123456789 

5.4.2.2 unsigned char» MSG CONTACT. S::contactVal 

The value of the contact. It should be encoded in ASCII. 

For example, the real phone number or email address. 


5.4.2.3 MSG STRING S_ MSG CONTACT S::contactName 


Indicates the display name of this contact. 


5.4.2.4 size_t MSG CONTACT S::extDataSize 


Indicates the size of the extension data which pExt Data point to. The unit is byte. 


5.4.2.5 voids MSG CONTACT _S::pExtData 


Extension data for contact. 
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Some data that is not covered in the structure can be put here, such as picture data and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Contact.h 
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5.5 MSG FILTER ID LIST S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.5.1 Detailed Description 


Represents a filter id list. 


It is composed of various filter ids. 


Data Fields 


e int iCount 
e MSG_FILTER_ID_T « filterlds 


5.5.2 Field Documentation 
5.5.2.1 int MSG FILTER _ID LIST _S::iCount 


Indicates the number of the filter id in the list. 


5.5.2.2 MSG FILTER _ID_T* MSG_FILTER_ID_LIST_S::filterIds 


Indicates the pointer to the filter id list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_FilterRule.h 
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5.6 _ MSG FILTER LIST_S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.6.1 Detailed Description 


Represents a filter list. 


It is composed of various MSG_FILTER_S. The first filter in the list has the highest priority. Framework 
will check the filter list from the first filter to the last one. Once the message satisfies the filter, framework 
stops checking other filters in the list and returns the autoStore and intercept properties of the 
current filter. 


Data Fields 


e intiCount 
¢ MSG_FILTER_S + filters 


5.6.2 Field Documentation 
5.6.2.1 int MSG FILTER LIST S::iCount 


Indicates the number of the filters in the list. 


5.6.2.2 MSG_FILTER_Sx _MSG_FILTER_LIST_S::filters 


The pointer to the filter list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_FilterRule.h 
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5.7 _MSG FILTER S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.7.1 Detailed Description 


Represents a filter. 


It represents the basic filter unit. 


Data Fields 


e MSG_FILTER_ID_T filterId 
e MSG_STRING_S filterName 
e bool autoStore 

e bool intercept 

e int valueLength 

e unsigned char * filterValue 


5.7.2 Field Documentation 
5.7.2.1 MSG_FILTER_ID_T_MSG_FILTER,_ S::filterld 


Indicates the filter type. 


The filter Id indicates the filter type. There are some predefined filter ids. Please refer to_MSG_FILTER_- 
ID_E 


5.7.2.2 MSG STRING _S_MSG FILTER S::filterName 


Indicates the display name for the filter. 


5.7.2.3 bool MSG FILTER S::autoStore 


Indicates whether the message should be automatically stored by framework, when it satisfies this filter. 


If it is set t rue, the message will be automatically stored by framework when the message satisfies this 
filter. By default, this message will be saved to Inbox in the default account. 


If it is set false, the message will not be stored by framework. 


5.7.2.4 bool _MSG_FILTER_S::intercept 


Indicates whether the message should be intercepted, when it satisfies this filter. 


When the message satisfies this filter, framework will send the message to this filter associated session, 
then check the intercept: 


If it is set true, the sessions whose priority are lower than this filter associated session will not receive this 
message. 


If it is set false, framework will send the message to all the other sessions that are interested in this message. 
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For details about session priority, please refer to MsgSetPriority in Messaging API [2]. 


5.7.2.5 int MSG_FILTER_S::valueLength 


Indicates the length of the filterValue. 


5.7.2.6 unsigned chars MSG FILTER _S::filter Value 


The value of the filter. 


For example, if the filter Id show that the message should be filtered by message type, the value maybe 
SMS, MMS. 


The documentation for this struct was generated from the following file: 


e Msg _Mapi_FilterRule.h 
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5.8 MSG FOLDER ID_LIST_S Struct Reference 


5.8 MSG FOLDER ID LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.8.1 Detailed Description 


Represents a folder id list. 


Data Fields 


e int iCount 
¢ MSG_FOLDER_ID_T x folderlds 


5.8.2 Field Documentation 
5.8.2.1 int MSG FOLDER _ID LIST _S::iCount 


The count of message ids 


5.8.2.2 MSG FOLDER_ID_T+ MSG FOLDER _ID_LIST_S::folderIds 


The pointer to the folder id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.9 MSG FOLDER S Struct Reference 


#include <Msg_Mapi_Folder.h> 


5.9.1 Detailed Description 


Represents a folder. 


For the more detailed information of folder, please refer to “Folder” in Messaging API [2] . This structure 
is extendable. Please refer to "Extendability" in Messaging API [2]. 


Data Fields 


MSG_FOLDER_ID_T folderld 
MSG_FOLDER_ID_T parentld 
MSG_STRING_S folderName 
MSG_STORAGE_ID_T storageld 
MSG_SORT_TYPE_T sortType 
MSG_FOLDER_TYPE_T folderType 
size_t commExtDataSize 

void x pCommExtData 


5.9.2 Field Documentation 
5.9.2.1 MSG FOLDER _ID_T_ MSG FOLDER S::folderId 


Indicates folder id. 


5.9.2.2 MSG FOLDER _ID_T MSG FOLDER S::parentId 


Indicates parent folder id. 


5.9.2.3 MSG STRING S_ MSG FOLDER S::folderName 


Indicates the folder name. 


5.9.2.4 MSG STORAGE ID_T_ MSG _FOLDER_S::storageId 


Indicates the storage id in which this folder (metadata and extension data) is stored. 


5.9.2.5 MSG SORT_TYPE_T_MSG_ FOLDER _S::sortType 


Indicates the sort type for the children nodes under this folder. 


5.9.2.6 MSG FOLDER _TYPE_T MSG FOLDER S::folderType 


Indicates the folder type which can be Inbox/Outbox... 
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5.9.2.7 size_t MSG FOLDER_S::commExtDataSize 


Indicates the size of pCommExtData 


5.9.2.8 voids MSG _FOLDER_S::pCommExtData 


Used to add extension data for framework storage plugin. 


For example, the extension data can be picture, max dispalying size and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Folder.h 
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5.10 


_MSG_ FW_STORAGE 5S Struct Reference 


#include <Msg_Framework_Storage_Interface.h> 


5.10.1 Detailed Description 


Represents a framework storage plugin handle. 


Data Fields 


MsgFwStoAttachStorage pAttachStorage 
MsgFwStoDetachStorage pDetachStorage 
MsgFwStoCheckStatus pCheckStatus 
MsgFwsStolnitStorage pInitStorage 
MsgFwStoGetStorageStatus pGetStorageStatus 
MsgFwStoAddMessage pAddMsg 
MsgFwStoUpdateMessage pUpdateMsg 
MsgFwStoDeleteMessage pDeleteMsg 
MsgFwStoDelAllMsgInFolder pDeleteAlIMsg 
MsgFwStoCountMessage pCountMsg 
MsgFwStoCountUnreadMessage pCountUnreadMsg 
MsgFwStoQueryMessage pQueryMsg 
MsgFwStoGetMsgCommInfo pGetMsgCommonInfo 
MsgFwStoGetMessageParentld pGetMsgParentld 
MsgFwStoReleaseMsgCommon pReleaseMsgCommon 
MsgFwStoReleaseMessageList pReleaseMessageldList 
MsgFwStoGetMessageldsByStorage pGetMessageldsByStorage 
MsgFwStoAddFolder pAddFolder 

MsgFwStoUpdateFolder pUpdateFolder 
MsgFwStoDeleteFolder pDeleteFolder 
MsgFwStoCountSubFolder pCountSubFolder 
MsgFwStoQueryFolder pQueryFolder 

MsgFwStoGetFolder pGetFolder 
MsgFwStoGetFolderParentld pGetFolderParentld 
MsgFwStoReleaseFolder pReleaseFolder 
MsgFwsStoReleaseFolderldList pReleaseFolderIdList 
MsgFwStoGetFolderByType pGetFolderByType 
MsgFwStoGetFolderldsByStorage pGetFolderldsByStorage 
MsgFwStoAddAccount pAddAccount 
MsgFwStoUpdateAccount pUpdateAccount 
MsgFwStoDelete Account pDelete Account 
MsgFwStoCountAccount pCountAccount 
MsgFwStoQueryAccount pQueryAccount 
MsgFwStoGetAccountIdsByRootlId pGetAccountIdsB yRootld 
MsgFwStoGetCommAccount pGetComAccount 
MsgFwStoReleaseCommAccount pReleaseComAccount 
MsgFwStoGetDefaultAccID pGetDefaultAccID 
MsgFwStoSetDefaultAccID pSetDefaultAccID 
MsgFwStoReleaseAccountIdList pReleaseAccountIdList 
MsgFwStoGetAccountldsByStorage pGetAccountIdsByStorage 
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5.10.2 
5.10.2.1 
5.10.2.2 
5.10.2.3 
5.10.2.4 
5.10.2.5 
5.10.2.6 
5.10.2.7 
5.10.2.8 
5.10.2.9 
5.10.2.10 
5.10.2.11 
5.10.2.12 
5.10.2.13 
5.10.2.14 
5.10.2.15 
5.10.2.16 


5.10.2.17 


5.10.2.18 
5.10.2.19 
5.10.2.20 
5.10.2.21 
5.10.2.22 
5.10.2.23 
5.10.2.24 
5.10.2.25 


5.10.2.26 


Field Documentation 

MsgFwStoAttachStorage MSG _FW_STORAGE S::pAttachStorage 
MsgFwStoDetachStorage MSG _FW_STORAGE S::pDetachStorage 
MsgFwStoCheckStatus MSG FW_STORAGE S::pCheckStatus 
MsgFwStoInitStorage MSG FW_STORAGE S::pInitStorage 
MsgFwStoGetStorageStatus_ MSG _FW_STORAGE S::pGetStorageStatus 
MsgFwStoAddMessage_MSG_FW_STORAGE_S::pAddMsg 
MsgFwStoUpdateMessage_MSG_FW_STORAGE_S::pUpdateMsg 


MsgFwStoDeleteMessage MSG FW_STORAGE S::pDeleteMsg 


MsgFwStoDelAllMsgInFolder_MSG_FW_STORAGE_S::pDeleteAllMsg 
MsgFwStoCountMessage_MSG_FW_STORAGE_S::pCountMsg 
MsgFwStoCountUnreadMessage_MSG_FW_STORAGE_S::pCountUnreadMsg 
MsgFwStoQueryMessage_MSG_FW_STORAGE S::pQueryMsg 
MsgFwStoGetMsgCommInfo _MSG_FW_STORAGE S::pGetMsgCommonInfo 
MsgFwStoGetMessageParentId MSG FW_STORAGE S::pGetMsgParentld 
MsgFwStoReleaseMsgCommon MSG FW_STORAGE S::pReleaseMsgCommon 
MsgFwStoReleaseMessageList_ MSG FW_STORAGE S::pReleaseMessageldList 


MsgFwStoGetMessageldsByStorage MSG _FW_STORAGE - 
S::pGetMessageldsByStorage 


MsgFwStoAddFolder _MSG_FW_STORAGE_S::pAddFolder 
MsgFwStoUpdateFolder_MSG_FW_STORAGE_S::pUpdateFolder 
MsgFwStoDeleteFolder_MSG_FW_STORAGE_S::pDeleteFolder 
MsgFwStoCountSubFolder_MSG_FW_STORAGE_S::pCountSubFolder 
MsgFwStoQueryFolder_ MSG FW_STORAGE S::pQueryFolder 
MsgFwStoGetFolder MSG _FW_STORAGE S::pGetFolder 
MsgFwStoGetFolderParentId MSG FW_STORAGE S::pGetFolderParentlId 
MsgFwStoReleaseFolder MSG _FW_STORAGE S::pReleaseFolder 


MsgFwStoReleaseFolderIdList MSG FW_STORAGE S::pReleaseFolderIdList 


5.10.2.27 


5.10.2.28 


5.10.2.29 
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MsgFwStoGetFolderByType_ MSG _FW_STORAGE S::pGetFolderByType 


MsgFwStoGetFolderIdsByStorage MSG _FW_STORAGE S::pGetFolderIdsByStorage 


MsgFwStoAddAccount MSG _FW_STORAGE S::pAddAccount 
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5.11 ~MSG MESSAGE ID_LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.11.1 Detailed Description 


Represents a message id list. 


Data Fields 


e int iCount 
e MSG_MESSAGE_ID_T x msglds 


5.11.2 Field Documentation 
5.11.2.1 int_MSG_MESSAGE_ID LIST _S::iCount 


The count of message ids 


5.11.2.2 MSG MESSAGE ID_Tx MSG MESSAGE ID _LIST_S::msgIds 


The pointer to the message id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.12 _MSG MESSAGE REQUEST _§S Struct Reference 


#include <Msg_Mapi_Message_Request.h> 


5.12.1 Detailed Description 


Represents a request that will be sent to messaging framework. 


Applications compose a request with this structure and send it to message framework via a connected 
session. This request Id is used to manage the request by framework. 


This structure is extendable. Please refer to “Extendability” in Messaging API [2]. 


Data Fields 


MSG_REQUEST_TYPE_T reqType 
MSG_MESSAGE_TYPE_S msgType 
MSG_REQUEST_ID_T regld 
MSG_MESSAGE_S x pMsg 

size_t extDataSize 


void x pExtData 


5.12.2 Field Documentation 


5.12.2.1 MSG _REQUEST_TYPE_T MSG MESSAGE_REQUEST_S::reqType 


Indicates the type of request. 
Some predefined types: MSG_REQUEST_TYPE_SEND, MSG_REQUEST_TYPE_SENDSAVE 


5.12.2.2 MSG _MESSAGE_TYPE_S MSG MESSAGE REQUEST_S::msgType 


Indicates the message type. 


Indicates the type of the message such as SMS, MMS, Email etc. 


5.12.2.3 MSG REQUEST_ID_T_ MSG MESSAGE REQUEST. S::reqlId 


Indicates the reqeust Id, the unique Id of the request. 


When applications use MsgSubmitReq (see Messaging API [2]) to submit a request to framework, this 
value will be set by framework and returned to applications. Applications should keep this id to trace the 
request’s status or cancel the request later. 


5.12.2.4 MSG MESSAGE _S*« MSG MESSAGE REQUEST_S::pMsg 


The pointer to message structure. 


When applications submit sending message request, this pointer shall point to the message that should be 
sent. 
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5.12.2.5 size_t MSG MESSAGE REQUEST_S::extDataSize 


Indicates the size of the extension data that pExtData point to. The unit is byte. 


5.12.2.6 void: MSG MESSAGE REQUEST _S::pExtData 


Used to add extension data for transport plugin. 
For example, this field can be used to extend new request for specific service. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message_Request.h 
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5.13 ~MSG MESSAGE S Struct Reference 


#include <Msg_Mapi_Message.h> 


5.13.1 Detailed Description 


Represents a message. 


This structure includes the common information of vaious specific service message, such as SMS, MMS, 
Email and i-mode message. 


This structure is extendable. Please refer to “Extendability” in Messaging API [2]. 


Data Fields 


MSG_MESSAGE_ID_T msgld 
MSG_FOLDER_ID_T parentld 
MSG_MESSAGE_TYPE_S msgType 
MSG_ACCOUNT_ID_T accountld 
MSG_STORAGE_ID_T storageld 
MSG_STRING_S subject 
MSG_CONTACT_S from 
MSG_CONTACT_LIST_S to 
MSG_STRING_S displaySubject 
MSG_STRING_S displayFrom 
MSG_STRING_S displayTo 
time_t displayTime 


size_t size 

MSG_STATUS_T status 
MSG_STATUS_T deliveryStatus 

bool hasAttachment 

bool hasDrmContent 
MSG_MESSAGE_PRIORITY_T priority 
size_t commExtDataSize 

void x pCommExtData 


size_t extDataSize 
void x pExtData 


5.13.2 Field Documentation 
5.13.2.1 MSG MESSAGE _ID_T_MSG MESSAGE S::msgld 


Indicates the message Id of this message. 


5.13.2.2 MSG _FOLDER_ID_T_ MSG MESSAGE S::parentId 


Indicates the parent folder ID. 


The parent is a folder. 
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5.13.2.3 MSG_MESSAGE_TYPE_S MSG MESSAGE S::msgType 


Indicates the message type. 


Indicates the type of the message such as SMS, MMS, Email, i-mode etc. 


5.13.2.4 MSG _ACCOUNT_ID_T _MSG_MESSAGE_S::accountld 


Indicates which account the message associated. 


5.13.2.5 MSG STORAGE _ID_T_MSG MESSAGE S::storageld 


Indicates where this message (metadata and extension data) is stored. 


If it is set MSG _STORAGE_DEFAULT, the message will be saved according to 
defaultMsgStorageld in its associated account.Otherwise, the message will be saved accord- 
ing this value. 


5.13.2.6 MSG _STRING_S _MSG_MESSAGE S::subject 


Indicates the subject of the message. 


5.13.2.7 MSG_CONTACT_S_MSG_MESSAGE,_S::from 


Indicates where the message comes from. 


5.13.2.8 MSG _CONTACT_LIST_S _MSG_MESSAGE S::to 


Indicates where the message will send to. 


5.13.2.9 MSG _STRING_S MSG MESSAGE S::displaySubject 


Indicates the display content for subject. 


5.13.2.10 MSG STRING_S_MSG_MESSAGE S::displayFrom 


Indicates the display content for from. 


5.13.2.11 MSG STRING_S_MSG_MESSAGE S::displayTo 


Indicates the display content for to. 


5.13.2.12 time t MSG MESSAGE S::displayTime 


Indicates the display content for time. 


For example, if the message is an incoming message, this value should be the time when the message 
arrived. Framework is responsible to set this value in this case. 
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If the message is an outgoing message, this value should be the time when the message be sent out. Appli- 
cation is responsible to set this value in this case. 


5.13.2.13 size_t MSG MESSAGE S::size 


Indicates the size of the message. The unit is byte. 


5.13.2.14 MSG STATUS_T _MSG_MESSAGE,_S::status 


Indicates the message’s local status, such as read/unread/replied/forwarded/protected ... 


5.13.2.15 MSG STATUS_T MSG MESSAGE S::deliveryStatus 


Indicates the delivery status of the message. 


5.13.2.16 bool MSG MESSAGE S::hasAttachment 


Indicates whether the message has attachment. 
If the message has attachment, it should be set t rue. 
If the message does not have attachment, it should be set false. 


5.13.2.17 bool MSG MESSAGE S::hasDrmContent 


Indicates whether the message attaches the DRM contents. 
If it is set t rue, the message attaches the DRM contents. 


If it is set false, the message does not attaches the DRM contents. 


5.13.2.18 MSG MESSAGE PRIORITY_T_ MSG MESSAGE S::priority 


Indicates the priority of this message. 


5.13.2.19 size t_ MSG MESSAGE S::commExtDataSize 


Indicates the size of the data that pCommExtData point to. The unit is byte. 


5.13.2.20 voids MSG MESSAGE S::pCommExtData 


Used to add extension data for framework storage plugin. 


This field is the extension data for framework storage plugin. For example, whether the message is replied 
can be regarded as an common extension attribute. 


5.13.2.21 size_t MSG MESSAGE S::extDataSize 


Indicates the size of the data that pExt Data point to. The unit is byte. 
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5.13.2.22 void: MSG MESSAGE S::pExtData 


Used to add extension data for message storage/transport plugin. 


This field is the extension data for storage/transport plugin. It is the place to put such message payload 
information as body and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message.h 
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5.14 MSG MESSAGE STATUS S Struct Reference 


#include <Msg_Mapi_Message_Status.h> 


5.14.1 Detailed Description 


Represents a message status. 


This stucture contains the information about the status of the request that application has submitted to 
framework. 


This structure is extendable. Please refer to “Extendability” in Messaging API [2]. 


Data Fields 


MSG_REQUEST_ID_T reqId 
MSG_ERROR_T error 
MSG_STATUS_T status 

bool isFinal 
MSG_MESSAGE_ID_T msgld 
size_textDataSize 


void x pExtData 


5.14.2 Field Documentation 
5.14.2.1 MSG_REQUEST_ID_T_MSG_MESSAGE_STATUS_S::reqld 


Indicates the corresponding request Id. 


5.14.2.2 MSG_ERROR_T_MSG_MESSAGE_STATUS_S::error 


Indicates the error code. 


5.14,2.3 MSG_STATUS_T _MSG_MESSAGE_STATUS_S::status 


Indicates the status of the corresponding request. 


5.14.2.4 bool_MSG_MESSAGE_STATUS_S::isFinal 


Indicates the request is finished or not. If the request is finished, no more status of this request will be sent 
to client and the request information will be removed from messaging framework. 


5.14.2.5  MSG_MESSAGE_ID_T _MSG_MESSAGE_STATUS_S::msgld 


Indicates the saved message id, it’s applicable when status is MSG_STATUS_SAVED_NOTSENT or 
MSG_STATUS_SENT_SAVED. 
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5.14.2.6 size_t MSG MESSAGE STATUS S::extDataSize 


Indicates the size of the extension data that pExtData point to. The unit is byte. 


5.14.2.7 void: MSG MESSAGE STATUS_S::pExtData 


Used to add extension data for transport plugin. 
For example, this field can be used to extend new status for specific service. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message_Status.h 
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5.15 MSG MESSAGE TYPE _LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.15.1 Detailed Description 


Represents a message types list. 


Data Fields 


e int iCount 
e MSG_MESSAGE_TYPE_S * pMsgTypes 


5.15.2 Field Documentation 
5.15.2.1 int_MSG_MESSAGE_TYPE_LIST_S::iCount 


The count of message types 


5.15.2.2 MSG_MESSAGE_TYPE_S« MSG _MESSAGE_TYPE_LIST_S::pMsgTypes 


The pointer to message types list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.16 ~-MSG MESSAGE TYPE S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.16.1 Detailed Description 


Represents a message type. 


This structure includes main type and sub type. 


Data Fields 


e MSG_MAIN_TYPE_T mainType 
e MSG_SUB_TYPE_T subType 


5.16.2 Field Documentation 


5.16.2.1 MSG MAIN TYPE_T MSG MESSAGE _TYPE_S::mainType 


Message main type 


5.16.2.2 MSG SUB_TYPE_T MSG MESSAGE TYPE _S::subType 


Message sub type 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


5.17 MSG _PLG_ STORAGE S Struct Reference 37 


5.17 _MSG PLG STORAGE 5S Struct Reference 


#include <Msg_Plugin_Storage_Interface.h> 


5.17.1 Detailed Description 


Represents a message storage plugin handle. 


Data Fields 


MsgPlgStoSetFwStoHandle pSetFwStoHandle 


MsgPlgStoAttachStorage pAttachStorage 


MsgPlgStoDetachStorage pDetachStorage 


MsgPlgStoCheckStatus pCheckStatus 


MsgPlgStoInitStorage pInitStorage 


MsgPlgStoGetStorageStatus pGetStorageStatus 


MsgPlgStoAddMessage pAddMsg 


MsgPlgStoUpdateMessage pUpdateMsg 


MsgPlgStoDeleteMessage pDeleteMsg 


MsgPlgStoDelAI/MsgInFolder pDelAlIMsg 


MsgPlgStoGetMessage pGetMsg 


MsgPlgStoReleaseMessage pReleaseMsg 


MsgPlgStoAddAccount pAddAccount 


MsgPlgStoUpdateAccount pUpdateAccount 


MsgPlgStoDeleteAccount pDeleteAccount 


MsgPlgStoGetAccount pGetAccount 


MsgPlgStoReleaseAccount pReleaseAccount 
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5.17.2 
5.17.2.1 
5.17.2.2 
5.17.2.3 
5.17.2.4 
5.17.2.5 
5.17.2.6 
5.17.2.7 
5.17.2.8 
5.17.2.9 
5.17.2.10 
5.17.2.11 
5.17.2.12 
5.17.2.13 
5.17.2.14 
5.17.2.15 
5.17.2.16 


5.17.2.17 


Field Documentation 

MsgPlgStoSetFwStoHandle_ MSG PLG STORAGE S::pSetFwStoHandle 
MsgPlgStoAttachStorage_ MSG _PLG_STORAGE S::pAttachStorage 
MsgPlgStoDetachStorage MSG _PLG_STORAGE S::pDetachStorage 
MsgPlgStoCheckStatus MSG _PLG STORAGE S::pCheckStatus 
MsgPlgStoInitStorage MSG _PLG_ STORAGE S::pInitStorage 
MsgPlgStoGetStorageStatus MSG _PLG_ STORAGE S::pGetStorageStatus 
MsgPlgStoAddMessage MSG PLG STORAGE S::pAddMsg 


MsgPlgStoUpdateMessage_ MSG PLG_ STORAGE _S::pUpdateMsg 


MsgPlgStoDeleteMessage MSG _PLG_STORAGE S::pDeleteMsg 
MsgPlgStoDelAlIMsgInFolder_MSG_PLG_STORAGE S::pDelAIIMsg 
MsgPlgStoGetMessage MSG _PLG_STORAGE _S::pGetMsg 
MsgPlgStoReleaseMessage MSG _PLG_ STORAGE S::pReleaseMsg 
MsgPlgStoAddAccount MSG _PLG_ STORAGE S::pAddAccount 
MsgPlgStoUpdateAccount_MSG_PLG STORAGE S::pUpdateAccount 
MsgPlgStoDeleteAccount_MSG PLG STORAGE S::pDeleteAccount 


MsgPlgStoGetAccount MSG PLG_ STORAGE S::pGetAccount 


MsgPlgStoReleaseAccount_ MSG PLG STORAGE _ S::pReleaseAccount 


The documentation for this struct was generated from the following file: 


e Msg_Plugin_Storage_Interface.h 
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5.18 MSG PLUGIN_FILTER MANAGER S Struct Reference 


#include <Msg_Plugin_Filter_Interface.h> 


5.18.1 Detailed Description 


Represents a filter manager. 


This structure contains the function pointers that filter rule plugin MUST implement. Filter rule plugin 
MUST implement all the functions and assemble them into this structure, then provide it to user. 


Data Fields 


e MsgPlgFilterInitialize pfIntialize 
e MsgPlgFilterFinalize pfFinalize 
e MsgPlgFilterCheckRules pfCheckRules 


5.18.2 Field Documentation 
5.18.2.1  MsgPlgFilterInitialize MSG _PLUGIN_FILTER_MANAGER S::pfIntialize 


The function pointer of initialize function. 


5.18.2.2 MsgPlgFilterFinalize MSG_PLUGIN_FILTER_MANAGER S::pfFinalize 


The function pointer of finalize function. 


5.18.2.3 MsgPlgFilterCheckRules_ MSG PLUGIN_FILTER_MANAGER S::pfCheckRules 


The function pointer of checkRules function. 


The documentation for this struct was generated from the following file: 


e Msg_Plugin_Filter_Interface.h 
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5.19 MSG PLUGIN_TRANSPORT 5S Struct Reference 


#include <Msg_Plugin_Transport_Interface.h> 


5.19.1 Detailed Description 


Represents a transport plugin handle. 


This structure contains the function pointers that transport plugin MUST implment. 


Data Fields 


e MsgPlgTransInitialize pfInitialize 

e MsgPlgTransFinalize pfFinalize 

e MsgPlgTransSubmitRequest pfSubmitRequest 

e MsgPlgTransCancelRequest pfCancelRequest 

e MsgPlgTransDiscardMsg pfDiscardMsg 

e MsgPlgTransRegisterListener pfRegisterListener 


5.19.2 Field Documentation 
5.19.2.1 MsgPlgTransInitialize MSG PLUGIN_TRANSPORT S::pfInitialize 


The function pointer of initialize. 


5.19.2.2 MsgPlgTransFinalize MSG _PLUGIN_TRANSPORT _S::pfFinalize 


The function pointer of finalize. 


5.19.2.3 MsgPlgTransSubmitRequest MSG PLUGIN_TRANSPORT_S::pfSubmitRequest 


The function pointer of submit request. 


5.19.2.4 MsgPlgTransCancelRequest MSG PLUGIN_TRANSPORT _ S::pfCancelRequest 


The function pointer of cancel request. 


5.19.2.5 MsgPlgTransDiscardMsg _MSG_PLUGIN_TRANSPORT_S::pfDiscardMsg 


The function pointer of discard message. 


5.19.2.6 MsgPlgTransRegisterListener MSG PLUGIN_TRANSPORT _S::pfRegisterListener 


The function pointer of register listener. 


The documentation for this struct was generated from the following file: 


e Msg_Plugin_Transport_Interface.h 
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5.20 _MSG QUERY_ID_LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.20.1 Detailed Description 


Represents a query Id list. 


Data Fields 


e int iCount 
e MSG_QUERY_ID_T * querylds 


5.20.2 Field Documentation 
5.20.2.1 int_MSG_QUERY_ID_LIST_S::iCount 


Indciates the count of the query Id in the list 


5.20.2.2 MSG_QUERY_ID_Tx_MSG_QUERY_ID_LIST_S::querylds 


Indicates the pointer to the query Id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.21 _MSG QUERY_LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.21.1 Detailed Description 


Represents a query list. 


Data Fields 


e int iCount 
e MSG_QUERY_S + queries 


5.21.2 Field Documentation 
5.21.2.1 int_MSG_QUERY_LIST _S::iCount 


Indciates the count of the query rules in the list 


5.21.2.2 MSG_QUERY_Sx _MSG_QUERY_LIST_S::queries 


Indicates the pointer to the query list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.22 _MSG QUERY S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.22.1 Detailed Description 


Represents a query rule. 


When applications need to query all SMS with subject containing some values, a MSG_QUERY_ID_T can 
be added as "MSG_QUERY_SMS_SUBJECT_CONTAIN". 


Refer to the following code: 


MSG_QUERY_S queryRulel; 

queryRule.queryId = MSG_QUERY_BY_ SUBJECT; 
queryRule.queryValue = "SearchingValue"; 
queryRule.valueLength = strlen(queryRule.queryValue) ; 


Data Fields 


e MSG_QUERY_ID_T queryld 
e int valueLength 
e unsigned char * query Value 


5.22.2 Field Documentation 
5.22.2.1 MSG_QUERY_ID_T_MSG_QUERY'_S::queryld 


Indicates what kind of rules should be taken when framework filters the messages 


5.22.2.2 int_MSG QUERY S::valueLength 


Indicates the length of the query Value 


5.22.2.3 unsigned chars _MSG_QUERY_S::queryValue 


Indicates the value of the query 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.23 MSG SORT_RULE _S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.23.1 Detailed Description 


Represents a sort rule. 


The sort rule structure includes sort type and sort order (ascending or descending). Applications can use 
the sort rule when querying messages. 


Data Fields 


e MSG_SORT_TYPE_T sortType 
e bool isAscending 


5.23.2 Field Documentation 


5.23.2.1 MSG _SORT_TYPE_T MSG SORT_RULE_S::sortType 


Indicates the sort type 


5.23.2.2 bool MSG _SORT_RULE_S::isAscending 


Indicates the sort order: ascending or descending 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.244 ~MSG SORT TYPE _LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.24.1 Detailed Description 


Represents a sort type list. 


Data Fields 


e intiCount 
e MSG_SORT_TYPE_T x sortTypes 


5.24.2 Field Documentation 


5.24.2.1 int_MSG_SORT_TYPE_LIST_S::iCount 


Indciates the count of the sort type in the list 


5.24.2.2 MSG_SORT_TYPE_Tx_MSG_SORT_TYPE_LIST_S::sortTypes 


Indicates the pointer to the sort type list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.25 MSG STORAGE ID _LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.25.1 Detailed Description 


Represents a storage id list. 


Data Fields 


e intiCount 
e MSG_STORAGE_ID_T x pStoragelds 


5.25.2 Field Documentation 
5.25.2.1 int_MSG_STORAGE_ID LIST_S::iCount 


The count of storage ids 


5.25.2.2 MSG STORAGE ID_T« MSG STORAGE ID _LIST_S::pStoragelds 


The pointer to storage id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.26 _MSG STRING S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.26.1 Detailed Description 


Represents a string. 


Data Fields 


e MSG_ENCODE_TYPE_T encodeType 
e int length 
e unsigned char * pString 


5.26.2 Field Documentation 


5.26.2.1 MSG ENCODE_TYPE_T_MSG STRING _S::encodeType 


The encoding type of the string 


5.26.2.2 int_MSG STRING S::length 


The length of string value 


5.26.2.3 unsigned charx _MSG_STRING _S::pString 


The string value 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.27 _MSG TRANSPORT LISTENER S Struct Reference 


#include <Msg_Plugin_Transport_Interface.h> 


5.27.1 Detailed Description 


Represents a transport listener handle. 


This structure contains the function pointers that transport listener of framework MUST implement. 


Data Fields 


e MsgPlgTransOnStatusChanged pfStatusChangedCallback 
e MsgPlgTransOnMsgIncoming pfReceiveMsgCallback 


5.27.2 Field Documentation 


5.27.2.1 MsgPlgTransOnStatusChanged _MSG_TRANSPORT_LISTENER_- 
S::pfStatusChangedCallback 


The function pointer of status changed callback. 


5.27.2.2 MsgPlgTransOnMsgIncoming _MSG_TRANSPORT_LISTENER_- 
S::pfReceiveMsgCallback 


The function pointer of receive message callback. 


The documentation for this struct was generated from the following file: 


e Msg_Plugin_Transport_Interface.h 
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File Documentation 


6.1 ComponentOverview.h File Reference 


6.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 


Defines 


e #define COMPONENT_OVERVIEW_H 


6.1.2 Define Documentation 


6.1.2.1 #define COMPONENT_OVERVIEW_H 
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6.2 Msg Framework_Storage_Interface.h File Reference 


6.2.1 Detailed Description 


Defines the interfaces that framework storage plugin MUST implement. 


These functions can be divided into four categories: 


incl 
incl 
incl 


inël 


Storage management. 


Message storage. 


Folder storage. 


Account storage. 


lude 
ude 
ude 
ude 
ude 


lude 


lude 


Data Structures 


_Mapi_Types.h" 


_Mapi_QueryRule.h" 


api_Storage_Manager.h" 


_Plugin_Types.h" 


_Mapi_Message.h" 


api_Folder.h" 


_Mapi_Account.h" 


¢ struct_MSG_FW_STORAGE_S 


Represents a framework storage plugin handle. 


Typedefs 


e typedef MSG_ERROR_T(*« MsgFwStoAttachStorage )MSG_STORAGE_ID_T Storageld) 


The prototype for attaching a specific storage by storage id. 


typedef MSG_ERROR_T(* MsgFwStoDetachStorage )(MSG_STORAGE_ID_T Storageld) 
The prototype for detaching a specific storage by storage id. 


typedef MSG_ERROR_T(* MsgFwStoCheckStatus )(MSG_STORAGE_ID_T Storageld, MSG_- 
PLG_STORAGE_STATUS_T xpStatus) 


The prototype for checking the status of the storage by storage id. 


typedef MSG_ERROR_T(*« MsgFwStolInitStorage )(MSG_STORAGE_ID_T Storageld) 


The prototype for initializing the storage. 


typedef MSG_ERROR_T(* MsgFwStoGetStorageStatus )(MSG_STORAGE_ID_T storageld, un- 
signed long long xtotalSize, unsigned long long *«usedSize, MSG_SIZE_UNIT_T xunit) 


Gets framework storage status by storage id. 
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typedef MSG_ERROR_T(* MsgFwStoAddMessage )(MSG_MESSAGE_S xpMsg) 


The prototype for adding a message into storage. 


typedef MSG_ERROR_T(* MsgFwStoUpdateMessage )(const MSG_MESSAGE_S *pMsg) 


The prototype for updating a message in storage. 


typedef MSG_ERROR_T(* MsgFwStoDeleteMessage )(MSG_MESSAGE_ID_T Msgld) 
The prototype for deleting a message. 


typedef MSG_ERROR_T(* MsgFwStoDelAllMsgInFolder )(MSG_FOLDER_ID_T Folderld) 


Deletes all messages in the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoCountMessage )(MSG_FOLDER_ID_T Folderld, bool bRe- 
cursive, const MSG_MESSAGE_TYPE_S *pMsgType, int *pCount) 


The prototype for getting the number of messages under the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoCountUnreadMessage )(MSG_FOLDER_ID_T Folderld, 
bool bRecursive, const MSG_MESSAGE_TYPE_S xpMsgType, int *pCount) 


The prototype for getting the number of unread messages under the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoQueryMessage (MSG_FOLDER_ID_T Folderld, bool bRe- 
cursive, int iBeginIndex, int iCount, const MSG_SORT_RULE_S *pSortRule, const MSG_- 
QUERY_LIST_S *pQueryList, MSG_MESSAGE_ID_LIST_S *pMsgldList) 


The prototype for getting the matched message ids under the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoGetMsgComminfo )(MSG_MESSAGE ID_T Msgld, 
MSG_MESSAGE S xx*ppMsg) 


The prototype for returning the message common information. 


typedef MSG_ERROR_T(* MsgFwStoGetMessageParentlId )(MSG_MESSAGE ID_T Msgld, 
MSG_FOLDER_ID_T «pParentFolderld) 


The prototype for returning the folder id in which the message exists. 


typedef void(+ MsgFwStoReleaseMsgCommon )(MSG_MESSAGE_S xpMsg) 
The prototype for releasing the memory of MSG_MESSAGE_S allocated in MsgF wStoGetMsgCommInfo. 


typedef void(+ MsgFwStoReleaseMessageList KMSG_MESSAGE_ ID_LIST_S xpMsgldList) 
The prototype for releasing the memory of the pointer in MSG_MESSAGE_ID_LIST_S. 


typedef MSG_ERROR_T(* MsgFwStoGetMessageldsByStorage AMSG_STORAGE_ID_T Stor- 
ageld, MSG_MESSAGE ID_LIST_S *pMsglds) 


Returns the message Ids by storage Id. 


typedef MSG_ERROR_T(* MsgFwStoAddFolder KMSG_FOLDER_S xpFolder) 
The prototype for adding a new folder. 


typedef MSG_ERROR_T(* MsgFwStoUpdateFolder )(const MSG_FOLDER_S xpFolder) 
The prototype for updating a folder. 


typedef MSG_ERROR_T(*« MsgFwStoDeleteFolder )(MSG_FOLDER_ID_T folderld, bool recur- 
sive) 
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The prototype for deleting a folder. 


typedef MSG_ERROR_T(* MsgFwStoCountSubFolder KMSG_FOLDER_ID_T folderld, bool re- 
cursive, int *pCount) 


The prototype for getting the number of sub folders under the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoQueryFolder )(MSG_FOLDER_ID_T folderld, int iBegin- 
Pos, int iCount, bool recursive, MSG_FOLDER_ID_LIST_S *pFolderIdList) 


The prototype for querying the sub folder ids under the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoGetFolder )(MSG_FOLDER_ID_T folderld, MSG_- 
FOLDER_S **ppFolderInfo) 


The prototype for getting the folder information of the specified folder. 


typedef MSG_ERROR_T(* MsgFwStoGetFolderParentid )(MSG_FOLDER_ID_T  folderld, 
MSG_FOLDER_ID_T xpParentFolderld) 


The prototype for getting the parent folder id of a folder. 


typedef void(+ MsgFwStoReleaseFolder )(MSG_FOLDER_S *pFolderInfo) 
The prototype for releasing the memory block of a folder. 


typedef void(« MsgFwStoReleaseFolderIdList KAMSG_FOLDER_ID_LIST_S *pFolderIdList) 
The prototype for releasing a memory block of folder id list. 


typedef MSG_ERROR_T(* MsgFwStoGetFolderByType )(MSG_FOLDER_ID_T rootFolderld, 
MSG_FOLDER_TYPE_T folderType, MSG_FOLDER_ID_LIST_S xpFolderldList) 


The prototype for getting the folder by folder type for the specified root folder. 


typedef MSG_ERROR_T(« MsgFwStoGetFolderldsByStorage XMSG_STORAGE_ID_T stor- 
ageld, MSG_FOLDER_ID_LIST_S *pFolderldList) 


The prototype for getting all the folder id list on a specified storage. 


typedef MSG_ERROR_T(* MsgFwStoAddAccount )(MSG_ACCOUNT_S x*pAccount) 


The prototype for adding account common information into framework storage plugin. 


typedef MSG_ERROR_T(* MsgFwStoUpdateAccount )(const MSG_ACCOUNT_S *pAccount) 


The prototype for updating account common information. 


typedef MSG_ERROR_T(*« MsgFwStoDeleteAccount )(MSG_ACCOUNT_ID_T accountld) 


The prototype for deleting account common information. 


typedef MSG _ERROR_T(* MsgFwStoCountAccount )(const MSG_MESSAGE_TYPE_S 
*pMsgType, int *xpCount) 


The prototype for getting the accounts number of the specified message type. 


typedef MSG_ERROR_T(*  MsgFwStoQueryAccount const MSG_MESSAGE _TYPE_S 
*pMsgType, MSG_ACCOUNT_ID_LIST_S xpAccountldList) 


The prototype for querying the account id list of the specified message type. 


typedef MSG_ERROR_T(* MsgFwStoGetAccountIdsByRootId )(MSG_FOLDER_ID_T root- 
Folderld, MSG_ACCOUNT_ID_LIST_S *pAccountldList) 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.2 Msg_Framework_Storage_Interface.h File Reference 53 


The prototype for getting account ids by root folder id. 


typedef MSG_ERROR_T(* MsgFwStoGetCommAccount )(MSG_ACCOUNT_ID_T accountld, 
MSG_ACCOUNT_S xx*ppAccount) 


The prototype for getting account common information. 


typedef void(+ MsgFwStoReleaseCommAccount )(MSG_ACCOUNT_S *pAccount) 


The prototype for releasing account common information. 


typedef MSG_ERROR_T(* MsgFwStoGetDefaultAccID )(const MSG_MESSAGE_TYPE_S 
*pMsgType, MSG_ACCOUNT_ID_T *«pAccountld) 


The prototype for getting the default account id. 


typedef MSG_ERROR_T(* MsgFwStoSetDefaultAccID )(const MSG_MESSAGE_TYPE_S 
*pMsgType, MSG_ACCOUNT_ID_T accountld) 


The prototype for setting the default account id. 


typedef void(* MsgFwStoReleaseAccountIdList )(MSG_ACCOUNT_ID_LIST_S 
*pAccountldList) 


The prototype for release the memory of account id list. 


typedef MSG_ERROR_T(* MsgFwStoGetAccountIdsByStorage )(MSG_STORAGE_ID_T stor- 
ageld, MSG_ACCOUNT_ID_LIST_S *pAccountlIdList) 


The prototype for getting all the account ids on a specified storage. 


typedef struct_MSG_FW_STORAGE_S MSG_FW_STORAGE S 


Functions 


e MSG_ERROR_T MsgFwStoCreateHandle (MSG_FW_STORAGE_S *hFwStoHandle) 


Creates a framework storage plugin handle. 


e MSG_ERROR_T MsgFwStoDestroyHandle () 


Destroys a framework storage plugin handle. 


6.2.2 Typedef Documentation 
6.2.2.1 typedef struct _MSG_FW_STORAGE_S MSG_FW_STORAGE_S 
6.2.2.2 typedef MSG_ERROR_T(« MsgFwStoAddAccount)(MSG_ACCOUNT_S xpAccount) 


The prototype for adding account common information into framework storage plugin. 


This function is to add account common information into framework storage plugin.Mandatory fields of 
account structure MUST be valid, otherwise the function MUST be failed. The mandatory fields for adding 
operation are accoundId, msgType, rootFolderld, storageld, defaultMsgStorageld. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in. 
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Parameters: 


— pAccount is a pointer to the data user defined for this new account. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount is NULL. 


MSG_ERR_INVALID_ ACCOUNT Some mandatory fields of account structure are not filled or not 
valid. 


MSG_ERR_STORAGE_ FULL Storage is FULL. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.3 typedef MSG_ERROR_T(« MsgFwStoAddFolder)(MSG_FOLDER_S xpFolder) 


The prototype for adding a new folder. 


This function is to create a folder under the specified folder in framework storage plugin. Mandatory fields 
of folder structure MUST be valid, otherwise the function MUST be failed. The mandatory fields for 
creating operation are folderId, parent Id, storageld. If the sortType is invalid, the default value 
MSG_SORT_BY_UNKNOWN MUST be set. 


Parameters: 


— pFolder is a pointer to the new folder information. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolder is NULL. 
MSG_ERR_INVALID_FOLDER Mandatory fields are invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 
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Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.4 typedef MSG_ERROR_T(* MsgFwStoAddMessage)(MSG_MESSAGE S «pMsg) 


The prototype for adding a message into storage. 


This function is to add a message common information into framework storage. Mandatory fields of mes- 
sage structure MUST be valid, otherwise the function will be failed. The mandatory fields for adding 
operation are msgId, parentId, msgType, storageld. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 
Parameters: 


— pMsg is a pointer to a MSG_MESSAGE S struct. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsg is NULL. 
MSG_ERR_INVALID_MESSAGE The mandatory fields of message are invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 

MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.5 typedef MSG _ERROR_T(« MsgFwStoAttachStorage)(MSG_ STORAGE _ID_T Storageld) 


The prototype for attaching a specific storage by storage id. 


If the framework storage plugin uses the database, it can establish connection with the database and open 
the table in this function. 


If the framework storage uses the files, it can open the files in this function. 


For storage plugin mechanism, please refer to Framework Storage Plug-in and Message Storage Plug-in 
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Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_STORAGE_ERROR Storage error 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.6 typedef MSG_ERROR_T(« MsgFwStoCheckStatus)(MSG_STORAGE_ID_T Storageld, 
MSG_PLG_STORAGE_STATUS_T xpStatus) 


The prototype for checking the status of the storage by storage id. 


Parameters: 


— Storageld is an integer value indicating which storage. 


=> pStatus indicates the status of the storage. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_NULL_POINTER pStatus is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 
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6.2.2.7 typedef MSG_ERROR_T(« MsgFwStoCountAccount)(const MSG_MESSAGE_TYPE_S 
«pMsgType, int «pCount) 
The prototype for getting the accounts number of the specified message type. 


This function is to get the number of accounts for the specified message type, such as SMS, MMS and 
Email. If the pMsgType is NULL, the function MUST return the count of all accounts. If the pMsgT ype 
is a specified type, the function MUST return account count of that type. If the pMsgType doesn’t exist, 
MSG_ERR_INVALID_MSG_TYPE is returned. 


Parameters: 


— pMsgType is the message type to be counted. 


— pCount is a pointer to the account number. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.8 typedef MSG_ERROR_T(« MsgFwStoCountMessage)(MSG_FOLDER_ID_T Folderld, 
bool bRecursive, const MSG_MESSAGE_TYPE_S xpMsgType, int «pCount) 


The prototype for getting the number of messages under the specified folder. 


Note: 
If pMsgType is NULL, it MUST return the messages number of all the message types. 


Parameters: 
— Folderld indicates the folder to be counted. 
— bRecursive indicates whether count the folder recursively. 
< pMsgType points to the message type which should be counted. 


— pCount is a integer pointer. 


Returns: 


MSG_ERROR_T 
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Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.9 typedef MSG_ERROR_T(* MsgFwStoCountSubFolder)(MSG_FOLDER_ID_T folderld, 
bool recursive, int «pCount) 
The prototype for getting the number of sub folders under the specified folder. 


This function is to get the number of sub folders under the specified folder. It can do a recursive or non- 
recursive deleting operation based on the value of parameter recursive. 


Parameters: 
— folderld indicates the querying folder id. 
— recursive indicates that this operation is recursive or non-recursive. 


=> pCount is a pointer to the number of sub folders. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.2.2.10 typedef MSG_ERROR_T(« MsgFwStoCountUnreadMessage)(MSG_FOLDER_ID_T 
Folderld, bool bRecursive, const MSG_MESSAGE_TYPE_S «pMsgType, int «pCount) 


The prototype for getting the number of unread messages under the specified folder. 


Note: 


If pMsgType is NULL, it MUST return the messages number of all the message types. 


Parameters: 
— Folderld indicates the folder to be counted. 
— bRecursive indicates whether count the folder recursively. 
< pMsgType points to the message type which should be counted. 


— pCount is a integer pointer. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.11 typedef MSG_ERROR_T(* MsgFwStoDelAIIMsgInFolder)(MSG_FOLDER_ID_T 
Folderld) 
Deletes all messages in the specified folder. 


This function is to delete all messages in the specified folder,but it will not delete the subfolders and the 
messages in the subfolders. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 
Parameters: 


— Folderld is a folder Id. 
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Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.12 typedef MSG_ERROR_T(« MsgFwStoDeleteAccount)(MSG_ACCOUNT_ID_T 
accountld) 
The prototype for deleting account common information. 


This function is to delete the account common information in framework storage plugin. For details about 
storage plugin mechanism, please refer to Framework Storage Plug-in and Message Storage Plug-in . 


Parameters: 


— accountld identifies the specific account need to be delete. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.2.2.13 typedef MSG_ERROR_T(« MsgFwStoDeleteFolder)(MSG_FOLDER_ID_T folderld, 
bool recursive) 
The prototype for deleting a folder. 


This function is to delete a folder in framework storage plugin. It can do a recursive or non-recursive 
deleting operation based on the value of parameter recursive. If the parameter recursive is false, 
the function MUST only delete this folder itself in case there is no content in this folder, otherwise MSG_- 
ERR_NOT_EMPTY_FOLDER will be returned. If the parameter recursive is true, regardless of 
whether content is in this folder, the function will recursively delete all its sub folders, messages and 
this folder itself. 

Parameters: 

— folderId identifies the deleted folder. 


< recursive indicates that the deleting operation is recursive or non-recursive. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 


MSG_ERR_NOT_EMPTY_FOLDER When recursive is false and the deleted folder has sub- 
folders or messages. 


MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.14 typedef MSG_ERROR_T(« MsgFwStoDeleteMessage)(MSG_MESSAGE_ID_T Msgld) 


The prototype for deleting a message. 

This function is to delete a message common information in framework storage. 

For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 

Parameters: 


— Msgld indicates to be deleted message’s Id. 


Returns: 


MSG_ERROR_T 
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Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.15 typedef MSG_ERROR_T(* MsgFwStoDetachStorage)(MSG_STORAGE_ID_T 
Storageld) 

The prototype for detaching a specific storage by storage id. 

If the framework storage plugin uses the database, it can close connection with the database in this function. 


If the framework storage plugin uses the files, it can close the files in this function. 


Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation 
MSG_ERR_STORAGE_ERROR Storage error 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.16 typedef MSG_ERROR_T(« MsgFwStoGetAccountIdsByRootId)(MSG_FOLDER_ID_T 
rootFolderId, MSG_ACCOUNT_ID_LIST_S «pAccountIdList) 


The prototype for getting account ids by root folder id. 
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This function is to get all the account ids whose root folder id is the specified folder it. Framework will 
guarantee the input folder id is root folder. 


The memory of account Ids inside the parameter account IdList MUST be allocated in this func- 
tion. This function’s caller MSUT release memory by invoking MsgFwStoReleaseAccountIdList. However 
if this function is failed, the memory is NOT allocated in this function. 


Parameters: 


— rootFolderld is the querying root folder id. 


> pAccountldList is a pointer to the structure which contains account ids. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount IdList is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.17 typedef MSG_ERROR_T(« MsgFwStoGetAccountIdsByStorage)(MSG_STORAGE_ID_- 
T storageld, MSG_ACCOUNT_ID_LIST_S «pAccountIdList) 
The prototype for getting all the account ids on a specified storage. 


This function is to get all account ids on a specified storage. 


Parameters: 


— storageld indicates the queried storage. 


> pAccountldList is a pointer to the account id list. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount IdList is NULL. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 
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Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.18 typedef MSG_ERROR_T(« MsgFwStoGetCommAccount)(MSG_ACCOUNT_ID_T 
accountId, MSG_ACCOUNT_S ««ppAccount) 


The prototype for getting account common information. 


This function is to get the account common information. The account common information includes all the 
fields of structure MSG_ACCOUNT_S except for pExtData. The memory of parameter ppAccount 
MUST be allocated in this function. This function’s caller MSUT release memory by invoking MsgFw- 
StoReleaseCommAccount. However if this function is failed, the memory is NOT allocated in this function. 


Parameters: 


— accountld is the querying account id. 


— ppAccount is a pointer to a pointer to the structure which contains account common information. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppAccount is NULL. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


For how to release framework account memory, please refer to MsgFwStoReleaseCommAccount . 


Since: 


1.0 


6.2.2.19 typedef MSG_ERROR_T(« MsgFwStoGetDefaultAccID)(const 
MSG_MESSAGE_TYPE_S xpMsgType, MSG_ACCOUNT_ID_T xpAccountld) 
The prototype for getting the default account id. 


This function is to get the default account id for the specified message type.The message type cann’t to be 
NULL. 
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Parameters: 
— pMsgType is the specified message type. 
> pAccountld returns the default account id. 
Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsgType, pAccount Id are NULL. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 

Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.20 typedef MSG_ERROR_T(« MsgFwStoGetFolder/(MSG_FOLDER_ID_T folderld, 
MSG_FOLDER_S «xppFolderInfo) 


The prototype for getting the folder information of the specified folder. 


This function is to get all information of the specified folder, which includes common and extended in- 
formation. For this folder structure may has extended structure, framework storage plugin MUST allocate 
folder structure memory in this function. This function’s caller MUST release memory by invoking Ms- 
gFwStoReleaseFolder. However if this function is failed, the memory is NOT allocated in this function. 
Parameters: 

— folderId indicates the querying folder id. 

> ppFolderInfo is a pointer to a pointer to the folder detailed information structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppFoldertInfo is NULL. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 
Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 
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6.2.2.21 typedef MSG _ERROR_T(« MsgFwStoGetFolderByType)(MSG_FOLDER_ID_T 
rootFolderId, MSG_FOLDER_TYPE_T folderType, MSG_FOLDER_ID_LIST_S 
«pFolderIdList) 

The prototype for getting the folder by folder type for the specified root folder. 

This function is to get the folder by folder type for the specified root folder. For example, it can retrieve 

inbox/outbox folders of a root folder. 

Parameters: 


— rootFolderld indicates the root folder. 
— folderType indicates the searched folder type. 
> pFolderldList is a pointer to all the returned folder ids. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pFolderld is NULL or pFolderIdList is NULL. 
MSG_ERR_INVALID_FOLDER_TYPE Folder type is not valid for this operation. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.22 typedef MSG_ERROR_T(« MsgFwStoGetFolderIdsByStorage)(MSG_STORAGE_ID_T 
storageld, MSG_FOLDER_ID_LIST_S «pFolderIdList) 
The prototype for getting all the folder id list on a specified storage. 


This function is to get all folder ids on a specified storage. 


Parameters: 


— storageld indicates the queried storage. 


> pFolderIdList is a pointer to the folder id list. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
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MSG_ERR_NULL_POINTER pFolderldList is NULL. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.23 typedef MSG_ERROR_T(« MsgFwStoGetFolderParentId)(MSG_FOLDER_ID_T 
folderId, MSG_FOLDER_ID_T xpParentFolderld) 
The prototype for getting the parent folder id of a folder. 


This function is to get the parent folder id of a folder, and it MUST return -1 if it is a root folder. 


Parameters: 


— folderId indicates the querying folder id. 
> pParentFolderld is a pointer to the parent folder id. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pParentFolderiIdis NULL. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.24 typedef MSG_ERROR_T(« MsgFwStoGetMessageldsByStorage(MSG_STORAGE_ID - 
T Storageld, MSG_MESSAGE_ID_LIST_S xpMsglds) 

Returns the message Ids by storage Id. 

Applications need to allocate the structure pMsgIds. 


When this function returns successfully, the storage ids will be filled in pMsglds->msglds. Applications 
need to call MsgFwStoReleaseMessageList to release the memory of pMsglds->msglds. However if this 
function is failed, the memory is NOT allocated in this function. 
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Parameters: 


— Msgld indicates which message should be gotten. 
=> pMsglds is a pointer to a MSG_MESSAGE_ID_LIST_S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsglds is NULL. 
MSG_ERR_INVALID_STORAGE Message id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.25 typedef MSG_ERROR_T(« MsgFwStoGetMessageParentId)(MSG_MESSAGE_ID_T 
Msgld, MSG_FOLDER_ID_T «pParentFolderId) 


The prototype for returning the folder id in which the message exists. 


Parameters: 


— Msgld indicates which message should be gotten. 
> pParentFolderld a pointer to the parent folder id. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pParentFolderld is NULL. 
MSG_ERR_INVALID_FOLDER_ID Message id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.2.2.26 typedef MSG_ERROR_T(« MsgFwStoGetMsgCommInfo)(MSG_MESSAGE_ID_T 
Msgld, MSG_MESSAGE _S x*ppMsg) 
The prototype for returning the message common information. 


This function is to return the message common information including common extension data 
(pCommExtData) without specific extension data (pExtData). 


Note: 


Memory will be allocated inside this function. 


Parameters: 
— Msgld indicates which message should be gotten. 


=> ppMsg is a pointer to a message pointer. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppMsg is NULL. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.27 typedef MSG_ERROR_T(« MsgFwStoGetStorageStatus)(MSG_STORAGE_ID_T 
storageld, unsigned long long xtotalSize, unsigned long long «usedSize, 
MSG_SIZE_UNIT_T «unit) 


Gets framework storage status by storage id. 


This function is to get total size and used size of the specified framework storage. 


Parameters: 
— storageld is an integer value indicating which storage. 
— totalSize the total size in this storage. 
— usedSize used size in this storage. 


— unit the unit of the size. 
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Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER totalSize is NULL or usedSize is NULL or unit is NULL 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.28 typedef MSG_ERROR_T(« MsgFwStoInitStorage)(MSG_STORAGE_ID_T Storageld) 


The prototype for initializing the storage. 
This function is to create all the data for framework storage plugin on the storage. 


When this function returns successfully, all the necessary data will be created and be set with default values. 


Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation,data on this storage will be reseted. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.2 Msg_Framework_Storage_Interface.h File Reference 71 


6.2.2.29 typedef MSG_ERROR_T(« MsgFwStoQueryAccount)(const MSG_MESSAGE_TYPE_S 
xpMsgType, MSG_ACCOUNT_ID_LIST_S «pAccountIdList) 


The prototype for querying the account id list of the specified message type. 


This function is to get account id list for the specified message type. The parameter pAccount IdList is 
defined by the function caller, but the memory of its structure member account Ids MUST be allocated 
in this function. This function’s caller MUST release the memory by invoking MsgFwStoReleaseAccoun- 
tIdList. However if this function is failed, the memory is NOT allocated in this function. If the pMsgType 
is NULL, the function will return all account id list. If the pMsgType is the specified type, the function will 
return account id list of that type. If the pMsgType doesn’t exist, MSG_ERR_INVALID_MSG_TYPE is 
returned. 


Parameters: 


— pMsgType is the message type to be queried. 


— pAccountldList is a pointer to the account list. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccountIdList is NULL. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.30 typedef MSG_ERROR_T(« MsgFwStoQueryFolder)(MSG_FOLDER_ID_T folderld, int 
iBeginPos, int iCount, bool recursive, MSG_FOLDER_ID_LIST_S «pFolderIdList) 


The prototype for querying the sub folder ids under the specified folder. 


This function is to query all the sub folder id list under the specified folder, and it can do a recursive or 
non-recursive searching based on the value of parameter recursive. The parameter pFolderIdList 
MUST be defined outside this funtion, but the memory of its member folderIds MUST be allocated in 
this function. So the function caller MUST release memory by invoking MsgFwStoReleaseFolderldList. 
However if this function is failed, the memory is NOT allocated in this function. If folderld is MSG_- 
INVALID_1ID, this function will query all the folders which have no parent folder. 


Parameters: 


— folderId indicates the folder id which is needed to query. 


< iBeginPos is the start position of all the satisfied folders, it should be 0 or a positive number. If 
iBeginPos is negative, index begins from 0. 
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<— ¡Count is the maximum number of folder information the caller wishes to receive. If ¡Count is 
negative, this method is to get all satisfied folders. 


< recursive indicates whether this querying is recursive. 


> pFolderIdList is the returned folder id list. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 


MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage and the folder id is not 
MSG_INVALID_ID. 


MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.2.2.31 typedef MSG_ERROR_T(« MsgFwStoQueryMessage(MSG_FOLDER_ID_T Folderld, 
bool bRecursive, int iBeginIndex, int iCount, const MSG_SORT_RULE_S xpSortRule, 
const MSG_QUERY_LIST_S «pQueryList, MSG_MESSAGE_ID_LIST_S «pMsgIdList) 


The prototype for getting the matched message ids under the specified folder. 


If pQueryList is NULL,the function MUST return all messages in this folder. If pSort Rule is NULL, 
the sort type is depended on underlying storage. 


Parameters: 
— Folderld indicates the folder to be queried. 
— bRecursive indicates whether this searching is recursive. 
— iBeginIndex indicates start position. If iBeginIndex is negative, index begins from 0. 


— ¡Count is the maximum number of message information the caller wishes to receive. If ¡Count is 
negative, this method is to get all satisfied messages. 


— pSortRule is the pointer to the sort rule. 


— pQueryList is the pointer to the querylist. For query rule description,refer to MSG_QUERY_- 
LIST_S. 


— pMsgldList is a pointer to a MSG_MESSAGE_ID_LIST_S structure. 


Returns: 


MSG_ERROR_T 
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Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsgIdList is NULL. 

MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 

MSG_ERR_INVALID_SORT_TYPE Sort type is invalid. 

MSG_ERR_INVALID_QUERY_ID Query id is invalid. 

MSG_ERR_STORAGE_ERROR Storage error. 

MSG_ERR_PLUGIN+n the error code specific for plugin. 
Note: 

n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 

when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.32 typedef void(* MsgFwStoReleaseAccountIdList(MSG_ACCOUNT_ID_LIST_S 
*«pAccountIdList) 
The prototype for release the memory of account id list. 


This function is to release the memory of pointer accountIds inside MSG_ACCOUNT_ID_LIST_- 
S. If pAccountIdList or pAccountIdList->accountIds is NULL, nothing happens. If pAccountIdList or 
pAccountIdList->accountlds is invalid, undefined behavior. 


Note: 
This function MUST NOT free this structure itself. 


Parameters: 
— pAccountldList is a pointer to the account id list. 


Since: 


1.0 


6.2.2.33 typedef void(« MsgF wStoReleaseCommAccount)(MSG_ACCOUNT_S xpAccount) 


The prototype for releasing account common information. 


This function is to release the memory of account common information. The memory of account common 
information is allocated in function MsgFwStoGetCommAccount . 


If pAccount is NULL, nothing happens. If pAccount is invalid, undefined behavior. 


Parameters: 


— pAccount is a pointer to an account structure which contains account common information. 


Since: 


1.0 
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6.2.2.34 typedef void(* MsgFwStoReleaseFolder)(MSG_FOLDER_S «pFolderInfo) 


The prototype for releasing the memory block of a folder. 


This function is to release the memory of a folder, which is allocated in function MsgFwStoGetFolder. For 
the folder may has extended data structure, this function is the exclusive way to release that folder memory. 


If pFolderInfo is NULL, nothing happens. If pFolderInfo is invalid, undefined behavior. 


Parameters: 


— pFolderInfo is a pointer to the folder structure. 


Example for creating folder MsgFwStoGetFolder . 


Since: 


1.0 


6.2.2.35 typedef void(* MsgFwStoReleaseFolderIdList)(MSG_FOLDER_ID_LIST_S 
«pFolderIdList) 
The prototype for releasing a memory block of folder id list. 


This function is to release the memory of pointer folderIds inside MSG_FOLDER_ID_LIST_S. If 
pFolderldList or pFolderIdList->folderlds is NULL, nothing happens. If pFolderIdList or pFolderIdList- 
>folderlds is invalid, undefined behavior. 


Note: 


This function does NOT free this structure itself. 


Parameters: 


— pFolderldList is a pointer to the folder id list. 


Since: 


1.0 


6.2.2.36 typedef void(* MsgFwStoReleaseMessageList(MSG_MESSAGE_ID_LIST_S 
«pMsglIdList) 
The prototype for releasing the memory of the pointer in MSG_MESSAGE_ID_LIST_S. 


This function is to release the memory of msglds in MSG_MESSAGE_ID_LIST_S structure. If pMs- 
gldList or pMsglIdList->msglIds is NULL, nothing happens. If pMsgldList or pMsgldList->msglds is 
invalid, undefined behavior. 


This function is to release pMsgldList->msglds. It will not release pMsgldList itself. 


Parameters: 


— pMsgldList is a pointer to an MSG_MESSAGE_ID_LIST_S structure. 


Since: 


1.0 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.2 Msg_Framework_Storage_Interface.h File Reference 75 


6.2.2.37 typedef void(* MsgF wStoReleaseMsgCommon)(MSG_MESSAGE S xpMsg) 


The prototype for releasing the memory of MSG_MESSAGE S allocated in MsgFwStoGetMsgComminfo. 
If pMsg is NULL, nothing happens. If pMsg is invalid, undefined behavior. 


Parameters: 


— pMsg is a pointer to an MSG_MESSAGE S structure. 


Since: 


1.0 


6.2.2.38 typedef MSG_ERROR_T(* MsgFwsStoSetDefaultAccID) (const 
MSG_MESSAGE_TYPE_S xpMsgType, MSG_ACCOUNT_ID_T accountId) 

The prototype for setting the default account id. 

This function is to set the default account id for the specified message type. The pMsgType cannot be 

NULL. Each message type has its own default account. 

Parameters: 


— pMsgType is the message type. 


— accountld is used to set default account. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.39 typedef MSG_ERROR_T(« MsgFwStoUpdateAccount)(const MSG_ACCOUNT_S 
*pAccount) 


The prototype for updating account common information. 


The function is expected to update msgType, rootFolderld, storageld and defaultMsgStorageID for the 
account indentified by the given accountld as long as the given values are valid. Optionally, the function 
updates accountName, if necessary. 
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All account information except for accoundld can be updated. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in . 


If pAccount->storageld is different than original one, the account MUST be moved to updated storage. 


Parameters: 


— pAccount is a pointer to the data user defined to update the account. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount is NULL. 


MSG_ERR_INVALID_ACCOUNT Some mandatory fields of account structure are not filled or not 
valid. 


MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.40 typedef MSG_ERROR_T(« MsgFwStoUpdateFolder)(const MSG_FOLDER_S xpFolder) 


The prototype for updating a folder. 


This function is to update a folder in framework storage plugin. Following fields of folder structure MUST 
be valid, otherwise the function will be failed: 


folderlId, parentId, storageld. If the sortType is invalid, the default value MSG_SORT_BY_- 
UNKNOWN MUST be set. 


If pFolder->parentld is different than original one, the folder MUST be moved to updated destination 
folder. 


If pFolder->storageld is different than original one, the folder MUST be moved to updated storage. 


Parameters: 


— pFolder is a pointer to a structure which contains all updated information. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
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MSG_ERR_NULL_POINTER pFolder is NULL. 
MSG_ERR_INVALID_FOLDER Mandatory fields are invalid. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.2.41 typedef MSG_ERROR_T(« MsgFwStoUpdateMessage)(const MSG_MESSAGE S 
x«pMsg) 
The prototype for updating a message in storage. 


The function is to update message common data for the message indentified by the given msgld as long as 
the given values are valid in framework storage. 


Following fields of message structure MUST be valid, otherwise the function will be failed: 
msgid, parentlId, msgType, storageld. 


If pMsg->parentld is different than original one, the message MUST be moved to updated destination 
folder. 


If pMsg->storageld is different than original one, the message MUST be moved to updated storage. 

For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 

Parameters: 


— pMsg is a const pointer to a MSG_MESSAGE S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsg is NULL. 
MSG_ERR_INVALID_MESSAGE The mandatory fields of message are invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
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Since: 


1.0 


6.2.3 Function Documentation 


6.2.3.1 MSG _ERROR_T MsgFwStoCreateHandle (MSG_FW_STORAGE S + hFwStoHandle) 


Creates a framework storage plugin handle. 

This function is to provide framework storage plugin handle. This is the only way to get the framework 
storage plugin handle. 

Parameters: 


— hFwStoHandle is the pointer to a framework storage plugin handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER hFwStoHandle is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.2.3.2 MSG_ERROR_T MsgFwStoDestroyHandle () 


Destroys a framework storage plugin handle. 


This function is to destory a framework storage plugin handle. After destroying the handle, the handle can 
not be used anymore. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 


Since: 


1.0 
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6.3 Msg Mapi_Account.h File Reference 


6.3.1 Detailed Description 


Defines the account structure. 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Folder.h" 


Data Structures 


¢ struct_MSG_ACCOUNT_S 


Represents an account. 


Typedefs 


e typedef struct_MSG_ACCOUNT_S MSG_ACCOUNT_S 


6.3.2 Typedef Documentation 


6.3.2.1 typedef struct _MSG_ACCOUNT_S MSG_ACCOUNT_S 
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6.4 Msg Mapi_Contact.h File Reference 


6.4.1 Detailed Description 


Defines the contact structure. 


#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG _CONTACT_S 


Represents a contact. 


e struct MSG CONTACT _LIST_S 


Represents a contact list. 


Typedefs 


e typedef struct _MSG_CONTACT_S MSG_CONTACT_S 
» typedef struct _MSG_CONTACT_LIST_S MSG_CONTACT_LIST_S 


6.4.2 Typedef Documentation 
6.4.2.1 typedef struct _MSG_CONTACT_LIST_S MSG_CONTACT_LIST_S 


6.4.2.2 typedef struct _MSG_CONTACT_S MSG_CONTACT_S 
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6.5 Msg Mapi_FilterRule.h File Reference 


6.5.1 Detailed Description 


Defines the filter related structures. 


MSG_FILTER_S and MSG_FILTER_LIST_S define the criteria for session’s interested incoming mes- 
sages. 


MSG_FILTER_S represents the basic filter unit, with a pair of filter type and filter value. A filter is satisfied 
when the filter value meets the requirement of specific filter type. 


MSG_FILTER_LIST_S is composed of a series of various MSG_FILTER_S. A filter list is satisfied when 
one of filters in the list satisfied. 


The first filter in the list has the highest priority, the last the lowest. Framework will check the filter list 
from the first to the last. Once an incoming message satisfies one filter in the list, framwork would stop 
checking and return. 


The framework sends the satisfying messages to filter-list associated applications. If the intercept is set 
true, the lower priority session would not receive the messages. 


See MsgPlgFilterCheckRules. 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG FILTER _ID_LIST_S 


Represents a filter id list. 


¢ struct_MSG_FILTER_S 


Represents a filter. 


e struct MSG _FILTER_LIST_S 


Represents a filter list. 


Typedefs 


e typedef int MSG_FILTER_ID_T 
Represents the filter Id. 


e typedef struct _MSG_FILTER_ID_LIST_S MSG_FILTER_ID_LIST_S 
e typedef struct _MSG_FILTER_S MSG_FILTER_S 
e typedef struct _MSG_FILTER_LIST_S MSG_FILTER_LIST_S 


Enumerations 


e enum_MSG_FILTER_ID E ( 


MSG_FILTER_BY_UNKNOWN = 0, MSG_FILTER_BY_MSG_TYPE, MSG_FILTER_BY_- 
FROM, MSG_FILTER_BY_HAS_ATTACHMENT, 
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MSG_FILTER_BY_HAS DRM CONTENT, MSG_FILTER BY_SIZE_GT, MSG_FILTER_- 
BY_SIZE_LT, MSG_FILTER_BY_PRIORITY_GT, 


MSG_FILTER_BY_PRIORITY_LT, MSG_FILTER_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of filter id. 


6.5.2 Typedef Documentation 


6.5.2.1 typedef struct MSG FILTER_ID_LIST_S MSG _FILTER_ID_LIST_S 


6.5.2.2 typedef int MSG_FILTER_ID_T 


Represents the filter Id. 


A filter Id represents a unique filter type. The values for this type SHOULD be in _MSG_FILTER_ID_E 
or other extended filter Ids. 


6.5.2.3 typedef struct _MSG_FILTER_LIST_S MSG_FILTER_LIST_S 


6.5.2.4 typedef struct _MSG_FILTER_S MSG_FILTER_S 


6.5.3 Enumeration Type Documentation 
6.5.3.1 enum_MSG_FILTER_ID_E 


Represents the values of filter id. 
This enum is used as the value of MSG_FILTER_ID_T. 
For example: 

MSG_FILTER_S filter; 


filter.filterld = MSG_FILTER_BY_MSG_TYPE; 
filter.filterValue = (unsigned charx)malloc(sizeof (MSG_MESSAGE_TYPE_S)); 


MSG_MESSAGE_TYPE_S* msgType = (MSG_MESSAGE_TYPE_S*) filter.filterValue; 
msgType->mainType = MSG _MESSAGE_TYPE_SMS; 
msgType->subType = MSG_MESSAGE_TYPE_SMS_TEXT; 


//set the filter 


//the session will only receive SMS. 


Enumerator: 


MSG_FILTER BY UNKNOWN Unknown sort type. 


MSG_FILTER_BY_MSG_TYPE The messages whose message type are filterValue will be 
filtered out. filterValue should be MSG_MESSAGE_TYPE_S type. 


MSG_FILTER_BY_FROM The messages that come from filterValue will be filtered out. fil- 
terValue should be char x type, which is encoded in ASCII. 


MSG_FILTER_BY_HAS_ATTACHMENT Filter by whether the message has attachment. 
If filterValue is set 0, the messages that do not has attachment will be filtered out. 


If filterValue is set 1, the messages that have attachment will be filtered out. 
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MSG_FILTER_BY_HAS_DRM_CONTENT Filter by whether the message has DRM content. 
If filterValue is set 0, the messages that do not has DRM content will be filtered out. 


If filterValue is set 1, the messages that have DRM content will be filtered out. 


MSG_FILTER_BY_SIZE_GT The messages whose size are greater than or equal the 
filterValue will be filtered out. filterValue should be size_t type 


MSG_FILTER_BY_SIZE_LT The messages whose size are less than or equal the fi lterValue 
will be filtered out. filterValue should be size_t type 


MSG_FILTER_BY_PRIORITY_GT The messages whose priority are greater than or equal the 
filterValue will be filtered out. filterValue should be MSG_MESSAGE PRIORITY_T 
type. 

MSG_FILTER_BY_PRIORITY_LT The messages whose priority are less than or equal the 
filterValue will be filtered out. filterValue should be MSG_MESSAGE_PRIORITY_T 
type. 

MSG_FILTER_BY_USER_DEF_BEGIN User defined filter type begin value. 
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6.6 Msg Mapi_Folder.h File Reference 


6.6.1 Detailed Description 


Defines the folder related structures. 
For the detail information of folder , please refer to “Folder” in Messaging API [2] . 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_QueryRule.h" 


Data Structures 


e struct_MSG_FOLDER_S 


Represents a folder. 


Typedefs 
e typedef struct_MSG_FOLDER_S MSG_FOLDER_S 


6.6.2 Typedef Documentation 


6.6.2.1 typedef struct _MSG_FOLDER_S MSG_FOLDER_S 
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6.7 Msg Mapi_Message.h File Reference 


6.7.1 Detailed Description 


Defines the message structure. 
#include <stdlib.h> 
#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Contact.h" 


#include "time.h" 


Data Structures 


e struct_ MSG_MESSAGE_S 


Represents a message. 


Typedefs 
e typedef struct_MSG_MESSAGE_S MSG_MESSAGE_S 


6.7.2 Typedef Documentation 


6.7.2.1 typedef struct _MSG_MESSAGE_S MSG_MESSAGE_S 
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6.8 Msg Mapi_Message_Request.h File Reference 


6.8.1 Detailed Description 


Defines the message request structure. 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Message.h" 


Data Structures 


e struct _MSG_ MESSAGE REQUEST_S 


Represents a request that will be sent to messaging framework. 


Typedefs 


e typedef struct_MSG_ MESSAGE _REQUEST_S MSG_MESSAGE_REQUEST_S 


6.8.2 Typedef Documentation 


6.8.2.1 typedef struct _MSG_MESSAGE_REQUEST_S MSG_MESSAGE_REQUEST_S 
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6.9 Msg Mapi_Message_Status.h File Reference 


6.9.1 Detailed Description 


Defines the message status structure. 


#include "stdlib.h" 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct_MSG_MESSAGE_STATUS_S 


Represents a message status. 


Typedefs 


e typedef struct_MSG_MESSAGE_STATUS_S MSG_MESSAGE_STATUS_S 


6.9.2 Typedef Documentation 


6.9.2.1 typedef struct _MSG_MESSAGE_STATUS_S MSG_MESSAGE_STATUS_S 
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6.10 Msg Mapi_QueryRule.h File Reference 


6.10.1 Detailed Description 


Defines the query related structure. 


Query rule is used to query some specific messages from storage. Query rule list is composed of various 
query rules. Once the message satisfies one of the query rules in the list, it satisfies the query rule list. 


Applications should assemble a query rule list to filter the message even there is only one query rule. Please 
refer to MSG_QUERY_LIST_S 


Framework storage plugin SHOULD implement the query function and provide the supported queryId and 
query Value for user. 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG QUERY_ID_LIST_S 


Represents a query Id list. 


e struct _MSG_QUERY_S 


Represents a query rule. 


e struct_MSG_QUERY_LIST_S 


Represents a query list. 


e struct_MSG_SORT_TYPE_LIST_S 


Represents a sort type list. 


e struct_MSG_SORT_RULE_S 


Represents a sort rule. 


Typedefs 


e typedef int MSG_QUERY_ID_T 
The query id. 


typedef struct_MSG_QUERY_ID_LIST_S MSG_QUERY_ID_LIST_S 
typedef struct _MSG_QUERY_S MSG_QUERY_S 

typedef struct _MSG_QUERY_LIST_S MSG_QUERY_LIST_S 
typedef int MSG_SORT_TYPE_T 


Represents a sort type. 


typedef struct_MSG_SORT_TYPE_LIST_S MSG_SORT_TYPE_LIST_S 
typedef struct _MSG_SORT_RULE_S MSG_SORT_RULE_S 
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Enumerations 


e enum _MSG_QUERY_ID_E { 


MSG_QUERY_BY_UNKNOWN = 0, MSG_QUERY_BY_BEFORE DATETIME, MSG_- 
QUERY_BY_AFTER_DATETIME, MSG_QUERY_BY_FROM, 


MSG_QUERY_BY_TO, MSG_QUERY_BY_SUBJECT, MSG _QUERY_BY_SIZE, MSG _- 
QUERY_BY_STATUS, 


MSG_QUERY_BY_DELIVERY_STATUS, MSG _QUERY_BY_HASATTACHMENT, MSG_- 
QUERY_BY_HASDRMCONTENT, MSG_QUERY_BY_PRIORITY, 


MSG_QUERY_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of query Id. 


enum _MSG_SORT_TYPE_E { 


MSG_SORT_BY_UNKNOWN = 0, MSG_SORT_BY_DISPLAY SUBJECT, MSG_SORT_BY_- 
DISPLAY_FROM, MSG_SORT_BY_DISPLAY_TO, 


MSG_SORT_BY_DISPLAY_TIME, MSG_SORT_BY_ SIZE, MSG_SORT_BY_STATUS, MSG_- 
SORT_BY_DELIVERY_STATUS, 


MSG_SORT_BY_HASATTACHMENT, MSG_SORT_BY_HASDRMCONTENT, MSG_SORT_- 
BY_PRIORITY, MSG_SORT_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of sort types. 


6.10.2 Typedef Documentation 


6.10.2.1 typedef struct MSG QUERY_ID_LIST_S MSG_QUERY_ID_LIST_S 


6.10.2.2 typedef int MSG_QUERY_ID_T 


The query id. 


One query id presents a unique query type. 


6.10.2.3 typedef struct_MSG_QUERY_LIST_S MSG_QUERY_LIST_S 


6.10.2.4 typedef struct MSG QUERY_S MSG_QUERY_S 


6.10.2.5 typedef struct_ MSG SORT_RULE_S MSG_SORT_RULE_S 


6.10.2.6 typedef struct_MSG_SORT_TYPE_LIST_S MSG_SORT_TYPE_LIST_S 
6.10.2.7 typedef int MSG_SORT_TYPE_T 


Represents a sort type. 


The values for this type SHOULD be in _MSG_SORT_TYPE_E 
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6.10.3 Enumeration Type Documentation 
6.10.3.1 enum _MSG_QUERY_ID_E 


Represents the values of query Id. 


This enum is used as the value of MSG_QUERY_ID_T, which is used as an input parameter in method 
MsgQueryMessage (see Messaging API [2]). Framework storage plugin can extend the supported query Id 
in this enum. Applications can use the query Id when querying messages. 


Enumerator: 


MSG_QUERY_BY_UNKNOWN Unknown query Id 


MSG_QUERY_BY_BEFORE_DATETIME Query message whose time is before or equal to the 
datetime. 


MSG_QUERY_BY_AFTER_DATETIME Query message whose time is after or equal to the date- 
time 
MSG_QUERY_BY_FROM Query message by from_keyword 
MSG_QUERY_BY_TO Query message by to_keyword 
MSG_QUERY_BY_SUBJECT Query message by subject_keyword 
MSG_QUERY_BY_SIZE Query message by size 
MSG_QUERY_BY_STATUS Query message by status 
MSG_QUERY_BY_DELIVERY_STATUS Query message by delivery status 
MSG_QUERY_BY_HASATTACHMENT Query message by has attachment 
MSG_QUERY_BY_HASDRMCONTENT Query message by drm content 
MSG_QUERY_BY_PRIORITY Query message by priority 
MSG_QUERY BY USER_DEF_ BEGIN User defined query Id begin value 


6.10.3.2  enum_MSG_SORT_TYPE_E 


Represents the values of sort types. 


This enum is used as the value of MSG_SORT_TYPE_T. 


Enumerator: 


MSG_SORT_BY_UNKNOWN Unknown sort type 
MSG_SORT_BY DISPLAY SUBJECT Sort by display subject 
MSG_SORT_BY DISPLAY FROM Sort by display from 
MSG_SORT_BY_DISPLAY_TO Sort by display to 
MSG_SORT_BY_DISPLAY_ TIME Sort by display time 
MSG_SORT_BY_SIZE Sort by size 

MSG_SORT_BY STATUS Sort by status 
MSG_SORT_BY_DELIVERY_STATUS Sort by delivery status 
MSG_SORT_BY_HASATTACHMENT Sort by has attachment 
MSG_SORT_BY HASDRMCONTENT Sort by drm content 
MSG_SORT_BY PRIORITY Sort by priority 
MSG_SORT_BY USER_DEF_BEGIN User defined sort type begin value 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.11 Msg_Mapi_Types.h File Reference 


91 


6.11 Msg Mapi_Types.h File Reference 
6.11.1 Detailed Description 


Defines general types. 


Data Structures 


e struct _MSG MESSAGE TYPE_S 


Represents a message type. 


struct MSG MESSAGE TYPE_LIST_S 


Represents a message types list. 


struct MSG_STORAGE ID_LIST_S 


Represents a storage id list. 


struct_MSG_STRING_S 


Represents a string. 


struct MSG MESSAGE ID LIST_S 


Represents a message id list. 


struct _MSG_FOLDER_ID_LIST_S 


Represents a folder id list. 


struct _MSG_ACCOUNT_ID_LIST_S 


Represents an account id list. 


Defines 


e #define bool unsigned char 


Defines bool type. 


e #define true 1 


Defines true value. 


» #define false O 


Defines false value. 


e #define MSG_INVALID_MESSAGE_ID Oxffffffff 


Defines invalid id for message. 


e #define MSG_INVALID_ACCOUNT_ID Oxffff 


Defines invalid id for account. 


e #define MSG_INVALID_FOLDER_ID Oxffff 
Defines invalid id for folder. 
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e #define MSG_DEFAULT_ACCOUNT_ID 0 


Defines default account id. 


e #define MSG_DEFAULT_FOLDER_ID 0 
Defines default folder id. 


e #define MSG_ERROR_BEGIN (-255) 


Defines begin value for error. 


Typedefs 


e typedef int MSG_MAIN_TYPE_T 


Represents a message main type. 


typedef int MSG_SUB_TYPE_T 


Represents a message sub type. 


typedef struct_MSG_MESSAGE_TYPE_S MSG_MESSAGE_TYPE_S 
typedef struct _MSG_MESSAGE_TYPE_LIST_S MSG_MESSAGE_TYPE_LIST_S 
typedef int MSG_ERROR_T 


Represents an error code. 


typedef unsigned int MSG_PLUGIN_ERROR_T 


Error code specific for plugins. 


typedef int MSG_SESSION_PRIORITY_T 


Represents a session priority. 


typedef int MSG_MESSAGE_PRIORITY_T 


Represents a message priority. 


typedef int MSG_STATUS_T 


Represents a status. 


typedef int MSG_REQUEST_TYPE_T 


Represents a request type. 


typedef unsigned int MSG_REQUEST_ID_T 


Represents a request id, which is unique for each request. 


typedef unsigned int MSG_STORAGE_ID_T 


Represents a Storage id. 


typedef unsigned int MSG_MEDIA_TYPE_T 


Represents a media type. 


typedef unsigned int MSG_FOLDER_TYPE_T 
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Represents a folder type. 


typedef struct _MSG_STORAGE_ID_LIST_S MSG_STORAGE ID_LIST_S 
typedef int MSG_CONTACT_TYPE_T 


Represents a contact type. 


typedef int MSG_ENCODE_TYPE_T 


Represents an encoding type. 


typedef struct _MSG_STRING_S MSG_STRING_S 
typedef unsigned long MSG_MESSAGE_ID_T 


Represents a messsage id. 


typedef unsigned int MSG_FOLDER_ID_T 


Represents a folder id. 


typedef unsigned int MSG_ACCOUNT_ID_T 


Represents an account id. 


typedef struct _MSG_MESSAGE_ID_LIST_S MSG_MESSAGE_ID_LIST_S 
typedef struct _MSG_FOLDER_ID_LIST_S MSG_FOLDER_ID_LIST_S 
typedef struct _MSG_ACCOUNT_ID_LIST_S MSG_ACCOUNT_ID_LIST_S 
typedef int MSG_SIZE_UNIT_T 


Represents the unit of the size. 


Enumerations 


e enum_MSG_MAIN_TYPE E { 


MSG_MESSAGE_TYPE_UNKNOWN, MSG_MESSAGE_TYPE_MMS, MSG_MESSAGE - 
TYPE_EMAIL, MSG_MESSAGE_TYPE_SMS, 


MSG_MESSAGE_TYPE_IMODE } 


Represents the values of message main types. 


enum _MSG_ERROR_E { 


MSG_SUCCESS = 0, MSG_ERR_FS_ERROR = MSG_ERROR_ BEGIN - 1, MSG_ERR_FS_- 
FULL = MSG_ERROR_BEGIN - 2, MSG_ERR_INVALID_STORAGE = MSG_ERROR_BEGIN 
s3; 


MSG_ERR_INVALID_MSG_TYPE = MSG_ERROR_BEGIN - 4, MSG_ERR_INVALID_SORT_- 
TYPE = MSG_ERROR_BEGIN - 5, MSG_ERR_INVALID_FOLDER_ID = MSG_ERROR - 
BEGIN - 6, MSG_ERR_INVALID_STORAGE_REG = MSG_ERROR_BEGIN - 7, 


MSG_ERR_INVALID_CONNECTION = MSG_ERROR_BEGIN - 8, MSG _ERR_NULL_- 
POINTER = MSG_ERROR_ BEGIN - 9, MSG_ERR_INVALID_MESSAGE_ ID =MSG_ERROR - 
BEGIN - 10, MSG_ERR_INVALID_ACCOUNT_ID = MSG_ERROR_ BEGIN - 11, 


MSG_ERR_INVALID_QUERY_ID = MSG_ERROR_ BEGIN - 12, MSG_ERR_SESSION_NOT_- 
CONNECTED = MSG_ERROR_BEGIN - 13, MSG_ERR_INVALID_SESSION_HANDLE = 
MSG_ERROR_BEGIN - 14, MSG_ERR_PERMISSION_DENIED = MSG_ERROR_BEGIN - 15, 
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MSG_ERR_STORAGE_NOT_INIT = MSG_ERROR_BEGIN - 16, MSG_ERR_ STORAGE _- 
REG_NOT_INIT = MSG_ERROR_BEGIN - 17, MSG_ERR_INVALID_SESSION_PRIORITY = 
MSG_ERROR_BEGIN - 18, MSG_ERR_INVALID_FILTER_ID = MSG_ERROR_BEGIN - 19, 


MSG_ERR_INVALID_REQUEST = MSG_ERROR_BEGIN - 20, MSG_ERR_INVALID_- 
FOLDER_TYPE = MSG_ERROR_BEGIN - 21, MSG_ERR_ INVALID FOLDER = MSG _- 
ERROR_BEGIN - 22, MSG_ERR_NOT_EMPTY_FOLDER = MSG_ERROR_BEGIN - 23, 


MSG_ERR_INVALID_ACCOUNT = MSG_ERROR_BEGIN - 24, MSG_ERR_CONNECTION_- 
NOT_CONNECT = MSG_ERROR_BEGIN - 25, MSG_ERR_ INVALID MESSAGE = MSG_- 
ERROR_BEGIN - 26, MSG_ERR_STORAGE_ FULL = MSG_ERROR_BEGIN - 27, 


MSG_ERR_ROOTFOLDER_INUSE = MSG_ERROR_BEGIN - 28, MSG_ERR_ STORAGE _- 
ERROR = MSG_ERROR_BEGIN - 29, MSG_ERR_MEMORY_ERROR = MSG_ERROR_BEGIN 
- 30, MSG_ERR_COMMUNICATION_ERROR = MSG_ERROR_BEGIN - 31, 


MSG_ERR_ MAX NUMBER REACHED = MSG _ERROR BEGIN - 32, MSG_ERR - 
INVALID_REQUEST_ID = MSG_ERROR_BEGIN - 33, MSG_ERR_ UNKNOWN = MSG _- 
ERROR_BEGIN - 0x00008000, MSG_ERR_ FRAMEWORK RESERVE BEGIN = MSG_- 
ERROR_BEGIN - 0x00010000, 


MSG_ERR_FRAMEWORK_RESERVE_END = MSG_ERROR_BEGIN - 0x00020000, MSG_- 
ERR_PLUGIN = MSG_ERROR_BEGIN - 0x08000000, MSG_ERR_PLUGIN_DEF_BEGIN_- 
VALUE = MSG_ERR_PLUGIN } 


Represents the values of error codes. 


enum _MSG_SESSION_PRIORITY_E { 


MSG_SESSION_PRIORITY_LOWEST, MSG_SESSION_PRIORITY_LOW, MSG_SESSION_- 
PRIORITY_NORMAL, MSG_SESSION_PRIORITY_HIGH, 


MSG_SESSION_PRIORITY_HIGHEST } 


Represents the values of session priority. 


enum _MSG MESSAGE PRIORITY_E { MSG MESSAGE PRIORITY_LOW, MSG _- 
MESSAGE_PRIORITY_NORMAL, MSG_MESSAGE_PRIORITY_HIGH } 


Represents the values of message priority. 


enum _MSG_STATUS_E { 


MSG_STATUS_UNKNOWN = 0, MSG_STATUS_READ, MSG_STATUS_UNREAD, MSG_- 
STATUS_REPLIED, 


MSG_STATUS_FORWARDED, MSG_STATUS_DRAFT, MSG_STATUS_EDITING, MSG_- 
STATUS_PROTECTED, 


MSG_STATUS_SENDING, MSG_STATUS_SENT, MSG_STATUS_FAIL_TO_SEND, MSG_- 
STATUS_SAVED_NOTSENT, 


MSG_STATUS_SENT_NOTSAVED, MSG_STATUS_SENT_SAVED, MSG_STATUS_FAIL - 
TO_SENDSAVE, MSG_STATUS_REQ_CANCELLED, 


MSG_STATUS_USER_DEF_BEGIN = 0x08000000 } 


Represents the values of status. 


enum _MSG_REQUEST_TYPE E { 


MSG_REQUEST_TYPE_INVALID = 0, MSG_REQUEST_TYPE_RESERVED_BEGIN, MSG_- 
REQUEST_TYPE_SEND, MSG_REQUEST_TYPE_SENDSAVE, 


MSG_REQUEST_TYPE_RESERVED_END = MSG_REQUEST_TYPE_RESERVED_BEGIN + 
0x00001000, MSG_REQUEST_TYPE_USER_DEF_BEGIN = 0x08000000 } 
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Represents the values of request types. 


enum _MSG_STORAGE ID _VALUE_E { MSG_STORAGE UNKNOWN = 0, MSG _- 
STORAGE _ DEFAULT } 

enum _MSG_MEDIA_TYPE_E [ MSG_MEDIA_FLASH, MSG_MEDIA_REMOVABLE, MSG_- 
MEDIA_SIM } 


Represents the values of media types. 


enum _MSG_FOLDER_TYPE_E { 


MSG_FOLDER_TYPE_ROOT, MSG _FOLDER_TYPE_ INBOX, | MSG_FOLDER_TYPE_- 
OUTBOX, MSG_FOLDER_TYPE_DRAFTS, 


MSG_FOLDER_TYPE_SENT, MSG_FOLDER_TYPE_DELETED, MSG _FOLDER_TYPE_- 
USERDEFINE } 


Represents the values of folder types. 


enum _MSG_CONTACT_TYPE_E { MSG_CONTACT_TYPE_UNKNOWN = 0, MSG _- 
CONTACT_TYPE_EMAIL, MSG_CONTACT_TYPE_PLMN } 


Represents the values of Contact types. 


enum _MSG_ENCODE_TYPE E { 


MSG_ENCODE_UTF8, MSG_ENCODE_UTF16, MSG_ENCODE_ASCII, MSG_ENCODE_- 
GSM7BIT, 


MSG_ENCODE_UCS2, MSG_ENCODE_SHIFT_JIS } 


Represents the values of String encoding types. 


enum _MSG_SIZE UNIT_E { 


MSG_SIZE_UNIT_BYTE, MSG_SIZE_UNIT_KBYTE, MSG_SIZE UNIT_MBYTE, MSG_- 
SIZE_UNIT_GBYTE, 


MSG_SIZE_UNIT_NUMBER } 


6.11.2 Define Documentation 


6.11.2.1 #define bool unsigned char 


Defines bool type. 


6.11.2.2 #define false 0 


Defines false value. 


6.11.2.3 #define MSG_DEFAULT_ACCOUNT_ID 0 


Defines default account id. 


6.11.2.4 #define MSG_DEFAULT_FOLDER_ID 0 


Defines default folder id. 
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6.11.2.5 #define MSG_ERROR_BEGIN (-255) 


Defines begin value for error. 


6.11.2.6 #define MSG_INVALID_ACCOUNT_ID Oxffff 


Defines invalid id for account. 


6.11.2.7 #define MSG_INVALID_FOLDER_ID Oxffff 


Defines invalid id for folder. 


6.11.2.8 #define MSG_INVALID_ MESSAGE _ID Oxffffffff 


Defines invalid id for message. 


6.11.2.9 #define true 1 


Defines true value. 


6.11.3 Typedef Documentation 


6.11.3.1 typedef struct MSG ACCOUNT_ID_LIST_S MSG_ACCOUNT_ID_LIST_S 


6.11.3.2 typedef unsigned int MSG_ACCOUNT_ID_T 


Represents an account id. 


6.11.3.3 typedef int MSG_CONTACT_TYPE_T 


Represents a contact type. 


The values eor this type SHOULD be in _MSG_CONTACT_TYPE_E 


6.11.3.4 typedef int MSG_ENCODE_TYPE_T 


Represents an encoding type. 


The values for this type SHOULD be in _MSG_ENCODE_TYPE_E 


6.11.3.5 typedef int MSG_ERROR_T 


Represents an error code. 


The values for this type SHOULD be in _MSG_ERROR_E 
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6.11.3.6 typedef struct MSG FOLDER_ID_LIST_S MSG FOLDER ID LIST_S 


6.11.3.7 typedef unsigned int MSG_FOLDER_ID_T 


Represents a folder id. 


6.11.3.8 typedef unsigned int MSG_FOLDER_TYPE_T 
Represents a folder type. 

The values for this type SHOULD be in _MSG_FOLDER_TYPE_E 
6.11.3.9 typedef int MSG_MAIN_TYPE_T 


Represents a message main type. 


The values for this type SHOULD be in _MSG_MAIN_TYPE_E 


6.11.3.10 typedef unsigned int MSG_MEDIA_TYPE_T 


Represents a media type. 


The values for this type SHOULD be in MSG _MEDIA_TYPE_E 


6.11.3.11 typedef struct MSG_MESSAGE_ID_LIST_S MSG_MESSAGE_ID_LIST_S 


6.11.3.12 typedef unsigned long MSG_MESSAGE _ID_T 


Represents a messsage id. 


6.11.3.13 typedef int MSG_MESSAGE_PRIORITY_T 


Represents a message priority. 


The values for this type SHOULD be in _MSG_MESSAGE_PRIORITY_E 


6.11.3.14 typedef struct MSG MESSAGE TYPE_LIST_S MSG_MESSAGE_TYPE_LIST_S 


6.11.3.15 typedef struct _MSG_MESSAGE_TYPE_S MSG_MESSAGE_TYPE_S 


6.11.3.16 typedef unsigned int MSG_PLUGIN_ERROR_T 


Error code specific for plugins. 


6.11.3.17 typedef unsigned int MSG_REQUEST_ID_T 


Represents a request id, which is unique for each request. 


For details of request, please refer to “Request” in Messaging API [2] . 
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6.11.3.18 typedef int MSG_REQUEST_TYPE_T 

Represents a request type. 

The values for this type SHOULD be in _MSG_REQUEST_TYPE_E 
6.11.3.19 typedef int MSG_SESSION_PRIORITY_T 

Represents a session priority. 

The values for this type SHOULD be in _MSG_SESSION_PRIORITY_E 
6.11.3.20 typedef int MSG_SIZE_UNIT_T 


Represents the unit of the size. 


The values for this type SHOULD be in _MSG_SIZE_UNIT_E 


6.11.3.21 typedef int MSG_STATUS_T 


Represents a status. 


The values for this type SHOULD be in _MSG_STATUS_E 


6.11.3.22 typedef struct _MSG_STORAGE_ID_LIST_SMSG_STORAGE ID _LIST_S 


6.11.3.23 typedef unsigned int MSG_STORAGE_ID_T 


Represents a Storage id. 


For details please refer to “Storage” in Messaging API [2] . 


6.11.3.24 typedef struct _MSG_STRING_S MSG_STRING_S 
6.11.3.25 typedef int MSG_SUB_TYPE_T 


Represents a message sub type. 


Each main type message can be divided into some sub types. For instance of SMS, the sub types can be 
CLASSO SMS, CLASS2 SMS and so on. 
6.11.4 Enumeration Type Documentation 


6.11.4.1 enum_MSG_CONTACT_TYPE_E 


Represents the values of Contact types. 

When MSG_CONTACT_TYPE_EMAIL is used, the contact value is an email address; When MSG_- 
CONTACT_TYPE_PLMN is used, the contact value is a mobile number. 

Enumerator: 


MSG_CONTACT_TYPE_UNKNOWN The contact type is unknown 
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MSG_CONTACT_TYPE_EMAIL The contact type is for email address 
abc@example.comemail 


MSG_CONTACT_TYPE_PLMN The contact type is for phone number like +1012345678 


6.11.4.2 enum _MSG_ENCODE_TYPE_E 
Represents the values of String encoding types. 


Enumerator: 
MSG_ENCODE_UTF8 The string encoding type is UTF8 
MSG_ENCODE_UTFI16 The string encoding type is UTF16 
MSG_ENCODE_ASCIT The string encoding type is ASCII 
MSG_ENCODE_GSM7BIT The string encoding type is GSM7BIT 
MSG_ENCODE_UCS2 The string encoding type is UCS2 
MSG_ENCODE_SHIFT_]JIS The string encoding type is Shift JIS 


6.11.4.3 enum_MSG_ERROR_E 


Represents the values of error codes. 


Success code is zero, all error codes SHOULD be negative and smaller than MSG_ERROR_BEGIN 


Enumerator: 


MSG_SUCCESS Successful 

MSG_ERR_FS_ERROR File system error 

MSG_ERR_FS_FULL File system is full 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid 
MSG_ERR_INVALID_SORT_TYPE Sort type is invalid 
MSG_ERR_INVALID_FOLDER_ID Folder Id is invalid 
MSG_ERR_INVALID_STORAGE_REG Storage registry is invalid 
MSG_ERR_INVALID CONNECTION Connection is invalid 
MSG_ERR_NULL_POINTER Pointer is NULL 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid 
MSG_ERR_INVALID_ACCOUNT_ID Account id is invalid 
MSG_ERR_INVALID_QUERY_ID Query id is invalid 
MSG_ERR_SESSION_NOT_CONNECTED Session is not connected 
MSG_ERR_INVALID_SESSION_HANDLE Session handle is invalid 
MSG_ERR_PERMISSION_DENIED Permisssion is denied 
MSG_ERR_STORAGE_NOT_INIT Storage is not initialized 
MSG_ERR_STORAGE_REG_NOT_INIT Storage registry is not initialized 
MSG_ERR_INVALID_SESSION_PRIORITY Session priority is invalid 
MSG_ERR_INVALID_FILTER_ID Filter Id is invalid 


like 
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MSG_ERR_INVALID_REQUEST Request is invalid: Request type is unsupported; The message 
type in request is invalid. 


MSG_ERR_INVALID_FOLDER_TYPE Folder type is invalid 
MSG_ERR_INVALID_FOLDER Folder information is invalid 
MSG_ERR_NOT_EMPTY_FOLDER Folder is not empty 
MSG_ERR_INVALID_ACCOUNT Account information is invalid 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected 
MSG_ERR_INVALID_MESSAGE Connection is not connected 
MSG_ERR_STORAGE_FULL Storage is full 
MSG_ERR_ROOTFOLDER_INUSE Root folder is associated with account(s) 
MSG_ERR_STORAGE_ERROR Storage is error 
MSG_ERR_MEMORY_ERROR Memory is error 
MSG_ERR_COMMUNICATION_ERROR Communication between client and server is error 


MSG_ERR_MAX_NUMBER_REACHED Max number reached when adding message,account or 
folder 


MSG_ERR_INVALID_REQUEST_ID Request Id is invalid 

MSG_ERR_UNKNOWN Unknown errors 
MSG_ERR_FRAMEWORK_RESERVE_BEGIN Framework reserved error code begin value 
MSG_ERR_FRAMEWORK_RESERVE_END Framework reserved error code end value 
MSG_ERR_PLUGIN Generic error code for plugin 


MSG_ERR_PLUGIN_DEF_BEGIN_VALUE Plugin defined error code begin value. It's equal to 
MSG_ERR_PLUGIN 


6.11.4.4 enum_MSG_FOLDER_TYPE_E 


Represents the values of folder types. 


Enumerator: 
MSG_FOLDER_TYPE_ROOT Root folder 
MSG_FOLDER_TYPE_ INBOX InBox folder 
MSG_FOLDER_TYPE_OUTBOX OutBox folder 
MSG_FOLDER_TYPE_DRAFTS Draft folder 
MSG_FOLDER_TYPE_SENT Sent folder 
MSG_FOLDER_TYPE_ DELETED Trash folder 
MSG_FOLDER_ TYPE _USERDEFINE Folder is created by user 


6.11.4.5  enum_MSG_MAIN_TYPE_E 


Represents the values of message main types. 


Four message main types are predefined: SMS, MMS, Email and iMode. More main message types can be 
defined here. 
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Enumerator: 


MSG_MESSAGE_TYPE_UNKNOWN Unknown message type 
MSG_MESSAGE_TYPE_MMS MMS message 
MSG_MESSAGE_TYPE_EMAIL Email message 
MSG_MESSAGE_TYPE_SMS SMS message 
MSG_MESSAGE_TYPE_IMODE i-mode message 


6.11.4.6 enum_MSG_MEDIA _TYPE_E 
Represents the values of media types. 


Enumerator: 


MSG_MEDIA_FLASH Media type is flash 
MSG_MEDIA_REMOVABLE Media type is removable 
MSG_MEDIA_SIM Media type is SIM card 


6.11.4.7 enum _MSG MESSAGE PRIORITY_E 
Represents the values of message priority. 


Enumerator: 


MSG_MESSAGE_PRIORITY_LOW Low priority 
MSG_MESSAGE_PRIORITY_NORMAL Normal priority 
MSG_MESSAGE_PRIORITY_HIGH High priority 


6.11.4.8 enum _MSG_REQUEST_TYPE_E 


Represents the values of request types. 


This enum is used as the value of type MSG_REQUEST_TYPE_T. Each message plugin can define the 
supported request types in this enum. Application can use the request type to invoke plugin corresponding 
operation via framework. Note that the enum between MSG_REQUEST_TYPE_RESERVED_BEGIN and 
MSG_REQUEST_TYPE_RESERVED_END are reserved for framework. For details of request, please 
refer to “Request” in Messaging API [2] . 


Enumerator: 


MSG_REQUEST_TYPE_INVALID It’s used as the initial value to request type. 
MSG_REQUEST_TYPE_RESERVED_BEGIN Framework reserved begin value 
MSG_REQUEST_TYPE_SEND Request to send message. 

This request is used to send a message. After this request is submitted, following status may be 

triggered: 

MSG_STATUS_SENDING: Message is in sending. 

MSG_STATUS_SENT: Messag is sent successfully. 

MSG_STATUS_FAIL_TO_SEND: Message is fail to send. 

If the request is cancelled successfully, the message is not sent and following status is triggered: 

MSG_STATUS_REQ_ CANCELLED: Request is cancelled. 
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MSG_REQUEST_TYPE_SENDSAVE Request to send and save message. 
This request is used to send and save a message. After this request is submitted, following status 
may be triggered: 
MSG_STATUS_SENDING: Message is in sending. 
MSG_STATUS_SAVED_NOTSENT: Messag is saved but not sent. 
MSG_STATUS_SENT_NOTSAVED: Message is sent but not saved. 
MSG_STATUS_SENT_SAVED: Message is both saved and sent. 
MSG_STATUS_FAIL_TO_SENDSAVE: Message is neither saved nor sent. 
If the request is cancelled successfully, the message is not sent and not saved. Following status 
is triggered: 
MSG_STATUS_REQ_ CANCELLED: Request is cancelled. 
MSG_REQUEST_TYPE_RESERVED_END Framework reserved end value 


MSG_REQUEST_TYPE_USER_DEF_BEGIN User defined request type begin value 


6.11.4.9 enum_MSG_SESSION PRIORITY _E 
Represents the values of session priority. 


Enumerator: 
MSG_SESSION_PRIORITY_LOWEST Lowest priority 
MSG_SESSION_PRIORITY_LOW Low priority 
MSG_SESSION_PRIORITY_NORMAL Normal priority 
MSG_SESSION_PRIORITY_HIGH High priority 
MSG_SESSION_PRIORITY_HIGHEST Highest priority 


6.11.4.10 enum __MSG_SIZE_UNIT_E 


Enumerator: 
MSG_SIZE_UNIT_BYTE Unit is byte 
MSG_SIZE_UNIT_KBYTE Unit is kilo-byte 
MSG_SIZE_UNIT_MBYTE Unit is mega-byte 
MSG_SIZE_UNIT_GBYTE Unit is giga-byte 
MSG_SIZE_UNIT_NUMBER Unit is number 


6.11.4.11 enum _MSG_STATUS_E 


Represents the values of status. 


This enum is used as the value of type MSG_STATUS_T. The specific status for each message can be 
defined in this enum. For instance of Email, sending status can be defined to track the email sending 
progress. 


Enumerator: 


MSG_STATUS_ UNKNOWN Unknown status 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.11 Msg_Mapi_Types.h File Reference 103 


MSG_STATUS_READ Message is read 

MSG_STATUS_UNREAD Message is unread 
MSG_STATUS_REPLIED Message is replied 
MSG_STATUS_FORWARDED Message is forwarded 
MSG_STATUS_DRAFT Message is draft 

MSG_STATUS_EDITING Message is in editing 
MSG_STATUS_PROTECTED Message is protected 
MSG_STATUS_SENDING Message is sending 
MSG_STATUS_SENT Message is sent 
MSG_STATUS_FAIL_TO_SEND Message is fail to send 
MSG_STATUS_SAVED_NOTSENT Message is saved, but not sent 
MSG_STATUS_SENT_NOTSAVED Message is sent, but not saved 
MSG_STATUS_SENT_SAVED Message is sent and saved 
MSG_STATUS_FAIL_TO_SENDSAVE Message is not saved and not sent 
MSG_STATUS_REQ_ CANCELLED Request is cancelled 
MSG_STATUS_USER_DEF_BEGIN User defined status begin value 


6.11.4.12 enum MSG STORAGE ID_VALUE_E 


Enumerator: 


MSG_STORAGE_UNKNOWN 
MSG_STORAGE_DEFAULT The default storage 
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6.12 Msg Plugin Filter_Interface.h File Reference 


6.12.1 Detailed Description 


Defines the filter interfaces that filter plugin MUST implement. 
#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Message.h" 


#include "Msg_Mapi_FilterRule.h" 


Data Structures 


e struct MSG _PLUGIN_FILTER_MANAGER S 


Represents a filter manager. 


Typedefs 


e typedef MSG_ERROR_T(* MsgPlgFilterInitialize )0 


The prototype for initializing function of filter manager. 


e typedef void(« MsgPleFilterFinalize )() 
The prototype for finalizing function of filter manager. 


e typedef bool(* MsgPlgFilterCheckRules const MSG_MESSAGE_S xpMsg, const MSG_- 
FILTER_S xpFilter, bool *autoStore, bool «intercept) 


The prototype for checking filter rule function of filter manager. 


e typedef struct _MSG_PLUGIN_FILTER_MANAGER_S MSG_PLUGIN_FILTER_MANAGER_S 


Functions 


e MSG_ERROR_T MsgPlgFilterCreateHandle (MSG_PLUGIN_FILTER_MANAGER_S 
*pFilterHandle) 


Creates a filter manager handle. 


e MSG_ERROR_T MsgPlgFilterDestroyHandle () 


Destroys a filter manager handle. 


6.12.2 Typedef Documentation 


6.12.2.1 typedef struct _MSG_PLUGIN_FILTER_MANAGER_S MSG_PLUGIN_FILTER_- 
MANAGER_S 


6.12.2.2 typedef bool(« MsgPlgFilterCheckRules)(const MSG_MESSAGE_S «pMsg, const 
MSG_FILTER_S «pFilter, bool xautoStore, bool xintercept) 


The prototype for checking filter rule function of filter manager. 
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This function is to check filter rule. 


This function check wheather the message satisfies the filter rule, return the autoStore and intercept 
properties of current filter rule. 


For details, please refer to Filter Plug-in: Set Filter List to Filter Messages. 


Parameters: 


— pMsg is the pointer to the message that needs to be filtered. 
— pFilter is the pointer to the filter rule. 


> autoStore indicates whether the message should be stored by framework automatically. This field 
is valid only when this function returns t rue. 


— intercept indicates whether the message should be intercepted. This field is valid only when this 
function returns t rue. 


Returns: 


bool 


Return values: 


true the message satisfies the filter rule. 


false the message does not satisfy the filter rule. 


6.12.2.3 typedef void(* MsgPlgFilterFinalize)() 


The prototype for finalizing function of filter manager. 


This function is to do finalization tasks such as releasing memory and releasing file descriptors. 


Returns: 


void 


6.12.2.4 typedef MSG_ERROR_T(« MsgPlgFilterInitialize)() 


The prototype for initializing function of filter manager. 


This function is to do initialization tasks such as allocating memory and opening file descriptors. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS filter plugin initializes successfully. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
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6.12.3 Function Documentation 


6.12.3.1 MSG ERROR_T MsgPlgFilterCreateHandle (MSG_PLUGIN_FILTER_MANAGER 5S 
x pFilterHandle) 


Creates a filter manager handle. 


This function is to create the filter manaer handle. This is the only way to get the filter manager handle. 


Parameters: 
— pFilterHandle is a pointer to the filter manager handle. When this function return MSG_- 
SUCCESS, it will point to a valid filter manager handle. Otherwise it will be set to NULL. 
Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS creates the filter plugin handle successfully. 
MSG_ERR_NULL_POINTER pFilterHandle is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.12.3.2 MSG_ERROR_T MsgPlgFilterDestroyHandle () 


Destroys a filter manager handle. 

This function is to destroy the filter manager handle. This is the only way to destroy the filter manager 
handle. After destroying, the handle can no longer be used. 

Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS destroys the filter plugin handle successfully. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 
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6.13 Msg Plugin_Storage_Interface.h File Reference 


6.13.1 Detailed Description 


Defines the interfaces that message storage plugin MUST implement. 


These functions can be divided into three categories: 


e Storage management. 
e Message storage. 


e Account storage. 


include "Msg_Mapi_Types.h" 
include "Msg_Mapi_Storage_Manager.h" 
include "Msg_Plugin_Types.h" 


include "Msg_Mapi_Message.h" 


include sg_Mapi_Account.h" 


include "Msg_Framework_Storage_Interface.h" 


Data Structures 


e struct MSG _PLG_STORAGE S 


Represents a message storage plugin handle. 


Typedefs 


typedef MSG_ERROR_T(x MsgPlgStoSetFwStoHandle )(MSG_FW_STORAGE_S 
*pFwStoHandle) 


The prototype for setting framework storage plugin handle. 


typedef MSG_ERROR_T(* MsgPlgStoAttachStorage )MSG_STORAGE_ID_T Storageld) 
The prototype for attaching a specific storage by storage id. 


typedef MSG_ERROR_T(* MsgPlgStoDetachStorage )(MSG_STORAGE_ID_T Storageld) 
The prototype for detaching a specific storage by storage id.. 


typedef MSG_ERROR_T(* MsgPlgStoCheckStatus (KMSG_STORAGE_ID_T Storageld, MSG_- 
PLG_STORAGE_STATUS_T xpStatus) 


The prototype for checking the status of the storage by storage id. 


typedef MSG_ERROR_T(* MsgPlgStoInitStorage K—MSG_STORAGE_ID_T Storageld) 


The prototype for initializing the storage. 


typedef MSG_ERROR_T(* MsgPlgStoGetStorageStatus )(MSG_STORAGE_ID_T storageld, un- 
signed long long xtotalSize, unsigned long long *usedSize, MSG_SIZE_UNIT_T xunit) 


Gets specific message storage status by storage id. 
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typedef MSG_ERROR_T(*« MsgPlgStoAddMessage )(MSG_MESSAGE_S *pMsg) 


The prototype for adding a message into storage. 


typedef MSG_ERROR_T(*« MsgPlgStoUpdateMessage )(const MSG_MESSAGE_S x*pMsg) 
The prototype for updating a Message. 


typedef MSG_ERROR_T(*« MsgPlgStoDeleteMessage )(MSG_MESSAGE_ID_T Msgld) 


The prototype for deleting a message. 


typedef MSG_ERROR_T(x* MsgPlgStoDelAlIMsgInFolder )(MSG_FOLDER_ID_T Folderld) 


Deletes all messages in the specified folder. 


typedef MSG_ERROR_T(* MsgPlgStoGetMessage )(MSG_MESSAGE ID _T Msgld, MSG_- 
MESSAGE_S xxppMsg) 


The prototype for getting the message detail information. 


typedef void(* MsgPlgStoReleaseMessage )(MSG_MESSAGE_S «pMsg) 
The prototype for releasing the memory of MSG_MESSAGE_S allocated in MsgPlgStoGetMessage. 


typedef MSG_ERROR_T(* MsgPlgStoAddAccount )(MSG_ACCOUNT_S xpAccount) 


The prototype for adding a new account in message storage plugin. 


typedef MSG_ERROR_T(* MsgPlgStoUpdateAccount )(const MSG_ACCOUNT_S xpAccount) 


The prototype for updating an account. 


typedef MSG_ERROR_T(* MsgPlgStoDeleteAccount )(MSG_ACCOUNT_ID_T accountld) 


The prototype for deleting an account. 


typedef MSG_ERROR_T(*« MsgPlgStoGetAccount )(MSG_ACCOUNT_ID_T accountld, MSG_- 
ACCOUNT_S **ppAccount) 


The prototype for getting the detailed account information for the specified account. 


typedef void(* MsgPlgStoReleaseAccount )(MSG_ACCOUNT_S *pAccount) 


The prototype for releasing the memory block of a account structure. 


typedef struct_MSG_PLG_STORAGE_S MSG_PLG_STORAGE_S 


Functions 


MSG_ERROR_T MsgPlgStoCreateHandle (MSG_PLG_STORAGE_S *hPLGStorageHandle) 


Creates a message storage plugin handle. 


MSG_ERROR_T MsgPlgStoDestroyHandle () 


Destroys a message storage plugin handle. 
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6.13.2 Typedef Documentation 
6.13.2.1 typedef struct MSG _PLG_STORAGE_ S MSG _PLG STORAGE S 
6.13.2.2 typedef MSG_ERROR_T(« MsgPlgStoAddAccount)(MSG_ACCOUNT_S xpAccount) 


The prototype for adding a new account in message storage plugin. 


This function is to add a new account into message storage plugin. It MUST call the framework plu- 
gin’s corresponding function MsgFwStoAddAccount to synchronize account common information with 
framework storage. This function MUST guarantee the data integrity between framework storage plu- 
gin and message storage plugin. Mandatory fields of account structure MUST be valid, otherwise the 
function MUST be failed. The mandatory fields for adding operation are accoundld, msgType, 
rootFolderld, storageld, defaultMsgStorageld. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in . 
Parameters: 


— pAccount contains the data user defined for this new account. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount is NULL. 
MSG_ERR_INVALID_ACCOUNT Mandatory fields of account structure are invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.13.2.3 typedef MSG_ERROR_T(« MsgPlgStoAddMessage)(MSG_MESSAGE S «pMsg) 


The prototype for adding a message into storage. 


This function is to add a message into message plugin storage. It should call framework storage plugin’s 
corresponding MsgFwStoAddMessage to synchronize common message information with framework stor- 
age. This method should guarantee the data integrity between framework storage and message plugin 
storage.Mandatory fields of message structure MUST be valid, otherwise the function will be failed. The 
mandatory fields for adding operation are msgid, parent Id, msgType, storageld. 
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If storageId is MSG_STORAGE DEFAULT, the message MUST be added to the 
defaultMsgStorageld in its associated account. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 
Parameters: 


— pMsg is a pointer to a MSG_MESSAGE S struct. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsg is NULL. 
MSG_ERR_INVALID_MESSAGE Mandatory fields of message are invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.4 typedef MSG_ERROR_T(* MsgPlgStoAttachStorage)(MSG_STORAGE_ID_T 
Storageld) 
The prototype for attaching a specific storage by storage id. 


If the message storage plugin uses the database, it can establish connection with the database and open the 
table in this function. 


If the message storage plugin uses the files, it can open the files in this function. 


For storage plugin mechanism, please refer to Framework Storage Plug-in and Message Storage Plug-in 


Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
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MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.5 typedef MSG_ERROR_T(« MsgPlgStoCheckStatus)(MSG_STORAGE_ID_T Storageld, 
MSG_PLG_STORAGE_STATUS_T xpStatus) 


The prototype for checking the status of the storage by storage id. 


Parameters: 


— Storageld is an integer value indicating which storage. 


> pStatus indicates the status of the storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_NULL_POINTER pStatus is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.6 typedef MSG_ERROR_T(« MsgPlgStoDelAlIMsgInFolder)(MSG_FOLDER_ID_T 
Folderld) 
Deletes all messages in the specified folder. 


This function is to delete all messages in the specified folder,but it will not delete the specified folder’s 
subfolders and the messages in the subfolders. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 
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Parameters: 


— Folderld is a folder Id. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.7 typedef MSG_ERROR_T(* MsgPlgStoDeleteAccount(MSG_ACCOUNT_ID_T 
accountId) 


The prototype for deleting an account. 


This function is to delete an account in message storage plugin, and it MUST call the framework plugin 
memthod MsgFwStoDeleteAccount to delete corrresponding account common information in framework 
storage. This method MUST guarantee the data integrity between framework storage and message storage 
plugin. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in . 
Parameters: 


— accountld identifies the specific account need to be deleted. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_ACCOUNT_ID This account does not exist. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 
Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 
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6.13.2.8 typedef MSG_ERROR_T(« MsgPlgStoDeleteMessage)(MSG_MESSAGE ID_T Msgld) 


The prototype for deleting a message. 


This function is to delete a message in message plugin storage. It should call framework storage plugin’s 
corresponding MsgFwStoDeleteMessage to synchronize common message information with framework 
storage. This method should guarantee the data integrity between framework storage and message plugin 
storage. 


For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 
Parameters: 


— Msgld indicates to be deleted message’s Id. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.9 typedef MSG_ERROR_T(* MsgPlgStoDetachStorage(MSG_STORAGE_ID_T 
Storageld) 

The prototype for detaching a specific storage by storage id.. 

If the message storage plugin uses the database, it can close connection with the database in this function. 

If the message storage plugin uses the files, it can close the files in this function. 


For storage plugin mechanism, please refer to Framework Storage Plug-in and Message Storage Plug-in 


Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation 
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MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.13.2.10 typedef MSG_ERROR_T(« MsgPlgStoGetAccount)(MSG_ACCOUNT_ID_T accountld, 
MSG_ACCOUNT_S xx*ppAccount) 
The prototype for getting the detailed account information for the specified account. 


This function is to get the detailed account information for the specified account. The memory of out 
parameter ppAccount MUST be allocated in this function. For this account may has its own extended 
structure, The function’s caller MUST release its memeory by invoking MsgPlgStoReleaseAccount. How- 
ever if this function is failed, the memory is NOT allocated in this function. 


Parameters: 


— accountld indicates the queried account. 


— ppAccount is a pointer to a pointer to the structure which contains account information. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppAccount is NULL. 
MSG_ERR_INVALID_ACCOUNT_ID This account does not exist. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.13.2.11 typedef MSG_ERROR_T(« MsgPlgStoGetMessage)(MSG_MESSAGE _ID_T Msgld, 
MSG_MESSAGE S x*ppMsg) 


The prototype for getting the message detail information. 
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This function is to return the message detail information, including both common extension data 
(pCommExtData) and specific message extension data (pExtData). 


This function should call MsgFwStoGetMsgCommInfo provided by framework storage plugin to get the 
message common information. The memory for the common information is allocated in MsgFwStoGetMs- 
gCommInfo. This function should allocate the memory for the specific extension data (pExtDat a). How- 
ever if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— Msgld indicates to be returned messages Id. 


=> ppMsg is a pointer to the message pointer. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_NULL_POINTER ppMsg is NULL. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 


6.13.2.12 typedef MSG_ERROR_T(« MsgPlgStoGetStorageStatus)MSG_STORAGE_ID_T 
storageld, unsigned long long «totalSize, unsigned long long «*usedSize, 
MSG_SIZE_UNIT_T xunit) 

Gets specific message storage status by storage id. 


This function is to get total size and used size of the specified message storage. 


Parameters: 
— storageld is an integer value indicating which storage. 
— totalSize the total size in this storage. 
— usedSize used size in this storage. 


— unit the unit of the size. 


Returns: 


MSG_ERROR_T 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


116 File Documentation 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER totalSize is NULL or usedSize is NULL or unit is NULL. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.13.2.13 typedef MSG_ERROR_T(« MsgPlgStoInitStorage)(MSG_STORAGE_ID_T Storageld) 


The prototype for initializing the storage. 

This function is to create all the data for message storage plugin on the storage. 

If the plugin uses the database, it can create tables in the database in this function. 
If the plugin uses the files, it can create the files in this function. 


When this function returns successfully, all the data on this storage will be filled with default values. If the 
storage data already exists, this function should reset all the values. 


Parameters: 


— Storageld is an integer value indicating which storage. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation,data on this storage will be reseted. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.13.2.14 typedef void(« MsgPlgStoReleaseAccount)(MSG_ACCOUNT_S xpAccount) 


The prototype for releasing the memory block of a account structure. 


This function is to release the memory of a account structure. Message storage plugin MUST implement 
this function to release the memory of its own extended structure, and in this function it MUST call the 
framework storage plugin’s corresponding function MsgFwStoReleaseCommAccount to release common 
extended structure explicitly. This account memory is created by function MsgPlgStoGetAccount . 


If pAccount is NULL, nothing happens. If pAccount is invalid, undefined behavior. 


Parameters: 


— pAccount is a pointer to a account structure. 


Since: 


1.0 


6.13.2.15 typedef void(* MsgPlgStoReleaseMessage)(MSG_MESSAGE_S «pMsg) 


The prototype for releasing the memory of MSG_MESSAGE S allocated in MsgPlgStoGetMessage. 


This function is to release the memory for the specific extension data (pExtData) and it should also 
call MsgFwStoReleaseMsgCommon to release the message common information allocated in framework 
storage plugin. 


If pMsg is NULL, nothing happens. If pMsg is invalid, undefined behavior. 


Parameters: 


< pMsg is a pointer to an MSG_MESSAGE S structure. 


Since: 


1.0 


6.13.2.16 typedef MSG_ERROR_T(« MsgPlgStoSetFwStoHandle)(MSG_FW_STORAGE S 
«pF wStoHandle) 
The prototype for setting framework storage plugin handle. 


This function is to set the framework storage plugin handle to message storage plugin. The framework 
storage plugin handle is used to invoke the functions provided by framework storage plugin. This function 
will be called when the message storage plugin is firstly lauched by messaging framework. When the 
framework storage plugin is closed by messaging framework, this method will be called with parameter 
NULL. 

Parameters: 


— pF wStoHandle the pointer to framework storage plugin handle. 


Returns: 


MSG_ERROR_T 
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Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.2.17 typedef MSG_ERROR_T(« MsgPlgStoUpdateAccount)(const MSG_ACCOUNT_S 
*pAccount) 


The prototype for updating an account. 


The function is expected to update msgType, rootFolderld, storageld and defaultMsgStorageID for the 
account indentified by the given accountld as long as the given values are valid. Optionally, the function 
updates extension data given by pExtData and extDataSize, and accountName, if necessary. 


This function MUST call the framework plugin’s corresponding function MsgFwStoUpdateAccount to 
update common account information in framework storage. All account information except for accound id 
can be updated. This method MUST guarantee the data integrity between framework storage and message 
storage plugin. 


If pAccount->storageld is different than original one, the account MUST be moved to updated storage. 
For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in . 

Parameters: 


— pAccount contains the data user defined to update account. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pAccount is NULL. 

MSG_ERR_INVALID_ ACCOUNT Mandatory fields of account structure are invalid. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 
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6.13.2.18 typedef MSG_ERROR_T(« MsgPlgStoUpdateMessage)(const MSG_MESSAGE_S 
*pMsg) 
The prototype for updating a Message. 


The function is to update message data for the message indentified by the given msgld as long as the given 
values are valid in message plugin storage. 


It MUST call framework storage plugin’s corresponding MsgFwStoUpdateMessage to synchronize com- 
mon message information with framework storage. This method MUST guarantee the data integrity be- 
tween framework storage and message plugin storage. Following fields of message structure MUST be 
valid, otherwise the function will be failed: 


msgid, parentId,msgType, storageld. 


If pMsg->parentld is different than original one, the message MUST be moved to updated destination 
folder. 


If pMsg->storageld is different than original one, the message MUST be moved to updated storage. 

For details about storage plugin mechanism, please refer to Framework Storage Plug-in and Message Stor- 
age Plug-in 

Parameters: 


<— pMsg is a const pointer to a MSG_MESSAGE S structure. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsg is NULL. 
MSG_ERR_INVALID_MESSAGE Mandatory fields of message are invalid. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 
n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetStoragePluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
Since: 


1.0 


6.13.3 Function Documentation 


6.13.3.1 MSG_ERROR_T MsgPlgStoCreateHandle (MSG_PLG_STORAGE S + 
hPLGStorageHandle) 


Creates a message storage plugin handle. 


This function is to provide message storage plugin handle. This is the only way to get the message storage 
plugin handle. 
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Parameters: 


— hPLGStorageHandle is the pointer to a message storage plugin handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER hPLGStorageHandle is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error 


Since: 


1.0 


6.13.3.2 MSG _ERROR_T MsgPlgStoDestroyHandle () 


Destroys a message storage plugin handle. 


This function is to destory a message storage plugin handle. After destroying the handle, the handle can 
not be used anymore. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error 


Since: 


1.0 
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6.14 Msg Plugin _Transport_Interface.h File Reference 


6.14.1 Detailed Description 


Defines the transport interfaces that transport plugin MUST implement. 
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Data Structures 


api_Types.h" 


_Mapi_Message.h" 
_Mapi_Message_Status.h" 
_Mapi_FilterRule.h" 


_Mapi_Message_Request.h" 


api_Account.h" 


e struct _MSG_TRANSPORT_LISTENER_S 


Represents a transport listener handle. 


e struct _MSG_PLUGIN_TRANSPORT_S 


Represents a transport plugin handle. 


Typedefs 


typedef struct_MSG_PLUGIN_TRANSPORT_S MSG_PLUGIN_TRANSPORT_S 
typedef MSG_ERROR_T(* MsgPlgTransOnStatusChanged )(MSG_PLUGIN_TRANSPORT_S 
*pTransHandle, MSG_MESSAGE_STATUS_S xpStatus) 


The prototype for onStatusChanged callback of framework. 


typedef MSG_ERROR_T(* MsgPlgTransOnMsgIncoming )(MSG_PLUGIN_TRANSPORT_S 
*pTransHandle, MSG_MESSAGE_S xpMsg, MSG_MESSAGE_STATUS_S xpStatus, int «uid) 


The prototype for onMsgIncoming callback of framework. 


typedef struct_MSG_TRANSPORT_LISTENER_S MSG_TRANSPORT_LISTENER_S 
typedef MSG_ERROR_T(* MsgPlgTransInitialize JO 


The prototype for initializing function of transport plugin. 


typedef void(« MsgPlgTransFinalize )() 


The prototype for finalizing function of transport plugin. 


typedef MSG_ERROR_T(* MsgPlgTransSubmitRequest )(const MSG_MESSAGE REQUEST_S 
*pRequest, const MSG_ACCOUNT_S xpAccount) 


The prototype for submitting request function of transport plugin. 


typedef MSG_ERROR_T(* MsgPlgTransCancelRequest )(int reqId) 


The prototype for cancelling request function of transport plugin. 
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e typedef MSG_ERROR_T(* MsgPlgTransRegisterListener )(MSG_TRANSPORT_LISTENER_S 
*pListener) 


The prototype for registering listener function of transport plugin. 


e typedef MSG_ERROR_T(+* MsgPlgTransDiscardMsg )(int uid) 


The prototype for discarding an incoming message. 


Functions 


e MSG_ERROR_T MsgPlgTransCreateHandle (MSG_PLUGIN_TRANSPORT_S xpTransHandle) 


Creates a transport plugin handle. 


e MSG_ERROR_T MsgPlgTransDestroyHandle () 


Destroys a transport plugin handle. 


6.14.2 Typedef Documentation 

6.14.2.1 typedef struct MSG PLUGIN_TRANSPORT_S MSG_PLUGIN_TRANSPORT_S 
6.14.2.2 typedef struct MSG _TRANSPORT_LISTENER_S MSG_TRANSPORT_LISTENER_S 
6.14.2.3 typedef MSG_ERROR_T(« MsgPlgTransCancelRequest)(int reqId) 


The prototype for cancelling request function of transport plugin. 


This function is to cancel the request from framework according to the request Id. 


This is an asynchronous function. 


Parameters: 


— reqld is the request Id that refers to the request. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS cancels the request successfully. 


MSG_ERR_PLUGIN_BUSY transport plugin is busy to handle the request. In this case, framework 
will pass this error code to application. 


MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 
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6.14.2.4 typedef MSG_ERROR_T(« MsgPlgTransDiscardMsg)(int uid) 


The prototype for discarding an incoming message. 


This function is to discard a messaage. If no application is interested in the message, the framework invoke 
this function to inform plugin to discard the message. 


Parameters: 


< uid is the unique Id of the message. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS discards the message successfully. 
MSG_ERR_INVALID_MESSAGE_UID the uid of the message is invalid. 


MSG_ERR_PLUGIN_BUSY transport plugin is busy to handle the request. In this case, framework 
will pass this error code to application. 


MSG_ERR_PLUGIN+n the error code specific for plugin. 
Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


6.14.2.5 typedef void(« MsgPlgTransFinalize)() 


The prototype for finalizing function of transport plugin. 


This function is to do such finalization works as deregistering network etc. 


Returns: 


void 


6.14.2.6 typedef MSG_ERROR_T(« MsgPlgTransInitialize)0 


The prototype for initializing function of transport plugin. 
This function is to do such initialization works as registering network etc. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS transport plugin initializes successfully. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 
Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error 
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6.14.2.7 typedef MSG_ERROR_T(« MsgPlgTransOnMsgIncoming)(MSG_- 
PLUGIN_TRANSPORT_S «pTransHandle, MSG_MESSAGE S xpMsg, 
MSG_MESSAGE_STATUS_S «pStatus, int xuid) 


The prototype for onMsgIncoming callback of framework. 
This callback function will be invoked when a new message is incoming. 


Transport plugin MUST NOT implement this callback. Framework implement this callback function. 
Transport plugin just informs the framework the new message incoming event by calling this callback 
function. pMsg and pStatus will be transferred to application. 


Transport plugin allocates the memory for pMsg and pStatus. After MSG_PLG_Trans_- 
onReceiveMessage callback function returns, transport plugin should release the memory. 


Parameters: 


— pTransHandle is the pointer to the transport plugin handle. 


— pMsg is the pointer to the incoming message. Plugin should allocate the memory and release it 
when this callback function returns. 


— pStatus The status of the message. Plugin should allocate the memory and release it when this 
callback function returns. 


— uid is the unique id of the incoming message. Framework should keep this id, if no application is 
interested in the message, this id should be passed back to plugin to discard the message. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS transport plugin informs the framework the new message incoming event success- 
fully. 


MSG_ERR_INVALID_TRANS_HANDLE the transport plugin handle is invalid. 
MSG_ERR_NULL_POINTER pMsg is NULL or pStatus is NULL or uid is NULL. 


6.14.2.8 typedef MSG_ERROR_T(« MsgPlgTransOnStatusChanged)(MSG_- 
PLUGIN_TRANSPORT_S xpTransHandle, MSG_MESSAGE STATUS_S 
*pStatus) 


The prototype for onStatusChanged callback of framework. 


This callback function will be invoked when a message request's status changes. Transport plugin MUST 
NOT implement this callback. Framework implements this callback function. Transport plugin just informs 
the framework the statusChanged event by calling this callback function. pStatus will be transferred 
to application. 


Transport plugin allocates the memory for pStatus. After MSG_PLG_Trans_onStatusChanged 
callback function returns, transport plugin should release the memory. 
Parameters: 


— pTransHandle is the pointer to the transport plugin handle. 


— pStatus is the pointer to the changed status. Plugin shall allocate the memory and release it after 
call this callback function. 
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Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS transport plugin informs the framework the status changed event successfully. 
MSG_ERR_NULL_POINTER pStatus is NULL. 
MSG_ERR_INVALID_TRANS_HANDLE the transport plugin handle is invalid. 


6.14.2.9 typedef MSG_ERROR_T(« MsgPlgTransRegisterListener)(MSG_TRANSPORT_- 
LISTENER_S xpListener) 

The prototype for registering listener function of transport plugin. 

This function is to register transport listener. When transport event occurs (status change/new message 

incomes), callback function in transport listener should be invoked to inform the listener. 

Parameters: 

— pListener is the pointer to the transport listener that need to be registered into the transport plugin. 

If NULL is passed in, the previous registered listener will be deregistered. 

Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS register the listener successfully. 
MSG_ERR_NULL_POINTER pListener is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


6.14.2.10 typedef MSG_ERROR_T(« MsgPlgTransSubmitRequest)(const 
MSG_MESSAGE_REQUEST_S «pRequest, const MSG_ACCOUNT_S xpAccount) 

The prototype for submitting request function of transport plugin. 

This function is to submit the request from framework. 

If pRequest->reqType is invalid, MSG_ERR_INVALID_REQUEST MUST be returned. 


If pRequest->pMsg->msgType is not same to pRequest->msgType, MSG_ERR_INVALID_REQUEST 
MUST be returned. 


Following fields MUST be ignored: 
pReq->pMsg->msgld, pReq->pMsg->parentld, pReq->pMsg->storageld. 


Parameters: 


— pRequest is the pointer to the request from framework. 
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— pAccount is the pointer to the account from framework. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS submits request successfully. 
MSG_ERR_INVALID_REQUEST some information in request are invalid. 


MSG_ERR_PLUGIN_BUSY transport plugin is busy to handle the request. In this case, framework 
will pass this error code to application. 


MSG_ERR_NULL_POINTER pRequest is NULL or pAccount is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


6.14.3 Function Documentation 


6.14.3.1 MSG ERROR_T MsgPlgTransCreateHandle (MSG_PLUGIN_TRANSPORT S x 
pTrans Handle) 


Creates a transport plugin handle. 


This function is to provide transport plugin handle. This is the only way to get the transport plugin handle. 


Parameters: 


> pTransHandle is a pointer to transport plugin handle. When this function return MSG_SUCCESS, 
it will point to a valid transport plugin handle. Otherwise, it will be set to NULL. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS creates the transport plugin handle successfully. 
MSG_ERR_NULL_POINTER pTransHandle is NULL. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.14.3.2 MSG_ERROR_T MsgPlgTransDestroyHandle () 


Destroys a transport plugin handle. 


This function is to destory the transport plugin handle. After destroying the handle, the handle can not be 
used anymore. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS destroys the transport plugin handle successfully. 
MSG_ERR_PLUGIN+n the error code specific for plugin. 


Note: 


n is the plugin specific error code (MSG_PLUGIN_ERROR_T), which will be returned to application 
when MsgGetSessionPluginError() is called. n could be 0 if plugin doesn’t want to specify the error. 


Since: 


1.0 
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6.15 Msg Plugin_Types.h File Reference 


6.15.1 Detailed Description 


Defines general types for plugins. 


#include "Msg_Mapi_Types.h" 


Typedefs 


e typedef unsigned int MSG_PLG_STORAGE_STATUS_T 


Represents a storage status for plugins. 


Enumerations 


enum _MSG_PLG_STORAGE STATUS_E { MSG_PLG_MEDIA_NOT_AVAILABLE, MSG_- 
PLG_DATA_NOT_AVAILABLE, MSG_PLG_DATA_ AVAILABLE } 


Represents the values of storage status for plugins. 


enum _MSG_PLG_ERROR_E { MSG_ERR_INVALID_TRANS_HANDLE = MSG_ERR - 
FRAMEWORK_RESERVE_BEGIN - 1, MSG_ERR_ INVALID MESSAGE UID = MSG _- 
ERR_FRAMEWORK_RESERVE_BEGIN - 2, MSG_ERR_PLUGIN_BUSY = MSG_ERR - 
FRAMEWORK_RESERVE_BEGIN - 3 } 


Represents the values of error codes for plugins. 


enum _MSG_SUB_TYPE_E { MSG_MSG_TYPE_SMS_TEXT=0 } 


enum _MSG_FRAMEWORK_ERROR_E [ MSG_ERR_INVALID_PLUGIN_HANDLE = MSG_- 
ERR_FRAMEWORK_RESERVE_BEGIN - 1 } 


6.15.2 Typedef Documentation 
6.15.2.1 typedef unsigned int MSG_PLG_STORAGE_STATUS_T 


Represents a storage status for plugins. 


The values for this type SHOULD be in _MSG_PLG_STORAGE STATUS_E 


6.15.3 Enumeration Type Documentation 


6.15.3.1 enum_MSG_FRAMEWORK_ERROR_E 


Enumerator: 


MSG_ERR_INVALID_PLUGIN_HANDLE 
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6.15.3.2 enum _MSG_PLG_ERROR_E 


Represents the values of error codes for plugins. 
The values of error codes SHOULD be between MSG_ERR FRAMEWORK _RESERVE_BEGIN and 
MSG_ERR_FRAMEWORK_RESERVE_END. 
Enumerator: 
MSG_ERR_INVALID_TRANS_HANDLE Transport handler is invalid 
MSG_ERR_INVALID_MESSAGE_UID Message UID is invalid 
MSG_ERR_PLUGIN_BUSY Plugin is busy 


6.15.3.3 enum _MSG_PLG_STORAGE_STATUS_E 
Represents the values of storage status for plugins. 


Enumerator: 
MSG_PLG_MEDIA_NOT_AVAILABLE Storage media is not available 
MSG_PLG_DATA_NOT_AVAILABLE Storage media is ready but no data available 
MSG_PLG_DATA_AVAILABLE Storage media is ready and data is available too 


6.15.3.4 enum _MSG_SUB_TYPE_E 


Enumerator: 


MSG_MSG_TYPE_SMS_TEXT 
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7.1 Overview of the LiMo Messaging Plug-ins 
7.1.1 Plug-ins Classifying Plug-ins 
There are two dimension to classify plug-ins. The first dimension classifies the plug-in according to the 
following two categories: 
e Framework, defined in framework_plug-in directory 


e Service-specific, defined in msg_plug-in directory 


A plug-in must below to one of these categories. The second dimension calssifies the plug-in by the 
modules that the LiMo Messaging Framework provides for applications: 


e Filter (only in Framework) 
e Transport (only in Framework) 
e Storage (in both Framework and Service-specific) 


These categories are described in the following sections. 


The next figure shows the messaging system and the role of the Messaging Framework, plug-ins and 
applications in creating and receiving messages. 
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Figure 7.1: Messaging System Architecture 


7.1.1.1 Filter Plug-in 
There are two groups of functionality that filter plug-ins provide: 


e Defining and implementing concrete filter rule. This is used by applications. 


e Checking filter rule functions. This is used by the framework to check application’s filter rules and 
decide how to dispatch the incoming messages. 


The filter plug-in will be invoked in the framework once MAPI Session-related API is invoked. For more 
information on MAPI Session-related API, please refer to Message sending and receiving . The definition 
of this interface is in Msg_Plugin_Filter_Interface.h 


7.1.1.2 Transport Plug-in 


The transport plug-in is a bridge between the framework and the network. There are two occasions when 
this plug-in is used: 
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e The framework gets the network events from transport plug-in, then notify applications. It is respon- 
sible for notifying framework when a network event occurs. 


e The framework gets the requests from applications, then sends them to transport plug-in. The trans- 
port plug-in is responsible for translating the requests from the framework, then sending them to 
network (or other components) to get the corresponding service (e.g. send a SMS.) 


The transport plug-in will be invoked in the framework once MAPI Session-related API is invoked. 
For more information on MAPI Session-related API, please refer to Message sending and receiving 


The definition of this interface is in Msg_Plugin_Transport_Interface.h 


7.1.1.3 Framework Storage Plug-in 


The framework storage plug-in provides the storage related functionality, such as adding, updating, delet- 
ing, querying, counting, moving and getting common information of messages, accounts and folders. This 
common information is a collection of the generic information from each service-specific message plug-in 
storage, such as SMS, MMS, Email, and i-Mode messaging. The detail data will be stored in service- 
specific message storage plug-in. Please refer to Message storage plug-in. 


The purpose of creating the common information is for improving performance. The functions, such as 
adding, updating, deleting, moving data, in framework storage plug-ins will be called by message storage 
plug-in’s corresponding functions to synchronize common information. The other functions of Framework 
Storage Plug-in, such as querying and sorting, will be called directly by MAPI Storage corresponding 
methods for performance reasons. 


The definition of this interface is in Msg_Framework_Storage_Interface.h. 


7.1.1.4 Message Storage Plug-in 


Each service-specific message storage plug-in provides the service-specific storage related functionality, 
such as adding, updating, deleting, moving and getting detail information of messages and accounts. Each 
service-specific message storage plug-in has its own detail information of message and account. 


The purpose of creating the service-specific message detail information is to store the service-specific data. 


For example, the SMS storage plug-in has the specific knowledge on SMS format, and additional data that 
generic message structure does not cover. Each function of the message storage plug-in will be called by 
the corresponding functions in MAPI storage APIs. The functions in message storage plug-in, such as 
adding, updating, deleting, and moving data, SHOULD call framework storage plug-in’s corresponding 
methods to synchronize common information. 


The definition of this interface is in Msg_Plugin_Storage_Interface.h. 


7.1.1.5 Storage Registry 


Registry file information has the following format: 


[Groupname ] 
mediatype= 
storeld= 
canDeregister= 
name= 

path= 
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e Groupname is the group name for this configuration information. It collects the following informa- 
tion to associate it with a specific item of registry. 


e mediatype is an integer. It indicates the type of storage media location. 


e storeld is a unique storage identifier. 


e canDeregister is an integer. Valid values are: O for can deregister and 1 for cannot deregister.. Indi- 
cates whether or not the storage can be deregistered. 


e name is a String. It indicates the name of the storage. 


e path is a string. It indicates the full path of the storage location. 


The media type 1 for flash and media type 2 for SIM is defined in the following example: 


[storage-registry-iteml] 
mediatype=1 

storeld=2 
canDeregister=0 

name= xxx 
path=/usr/local/... 
[storage-registry-item2] 
mediatype=2 

storeld=1 
canDeregister=1 

name= xxx 
path=/usr/local/... 


There is only one storage registry file. All storage id information shall be written into it. Application 
developers MUST predefine standard storage ids and write the supported storage information into the 
storage registry file. 


When an application calls MsgListStorageRegistry or MsgGetStorageRegistry (see Messaging API [2]) the 
messaging framework will receive this command. Then the messaging framework will load and parse this 
storage registry file and return the result to the application. 


7.1.1.6 Storage Subsystem 


The following diagram represents the storage subsystem architecture. 
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Figure 7.2: Storage Subsystem Architecture Option 1 


Alternately, you can combine the framework storage plug-in and the message storage plug-in into one, as 
the diagram below shows. 
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Figure 7.3: Storage Subsystem Architecture Option 2 


7.1.2 Plug-in Configuration 


Plug-in developers MUST provide a plug-in configuration file in the following format: 


[Groupname ] 
type= 

name= 
capability= 
alive= 
language= 


queryrule= 
sorttype= 


Note: queryrule and sorttype are used only for framework storage plug-in configuration. The rest of the 
fields are for all plug-ins. 


e Groupname is the group name for this configuration information. It collects the information below 
and assigns it to one plug-in. The Groupname can be regarded as a separator between two plug-ins’ 
configuration information. 


e type indicates the plug-in’s type. It is an integer. (1 for transport plug-in, 2 for filter plug-in, 3 for 
framework storage plug-in, 4 for message storage plug-in) 


e name is a string that represents the full path of the plug-in. It tells framework where to find the 
plug-in. 
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capability indicates the capability of the plug-in. For transport and message storage plug-ins it in- 
dicates what message type this plug-in supports. Message types must be defined in the following 
manner: mainType:subType, with message types separated by comma. For filter plug-ins, it indi- 
cates what filter types the plug-in supports. Normally, it is a string list separated by commas. 


alive indicates whether or not the framework shall unload the plug-in after use. It is an integer. (0 for 
unload after use; 1 for always alive) 


language is a string value, indicating the programming language in which the plug-in is implemented. 
The supported values are c and cpp. 


queryrule is a string that indicates which query ids will be supported. Normally, it is a string list 
separated by commas. 


sorttype is a string that indicates which sort types will be supported. Normally, it is a string list 
separated by commas. 


The following example defines the SMS message type MSG_MESSAGE_ TYPE_SMS as 2, sub type 
MSG_MESSSAGE_TYPE_TEXT is 0, MSG_MESSSAGE_TYPE_PORT is 1. 


[1limo-transport-sms] 

type=1 
name=/usr/lib/libsmstransprovider.so 
capability=2:0,2:1 

alive=0 

language=c 


Suppose a filter plug-in supports the following filter ids: 1, 2, 3, 4, and 5. The configuration item should 
look like the following: 


[limo-filter] 

type=1 
name=/usr/lib/libfilter.so 
capability=1,2,3,4,5 
alive=0 

language=c 


There is only one plug-in configuration file. All plug-ins’ information shall be written there. 


When the framework is initialized, it loads and parses this configuration file, then loads and manages all 
the required plug-ins according to the information in the file. The framework gets the capability of each 
plug-in, and dispatches messages, requests and other actions to the proper plug-in according to their types 
and capabilities. 


7.1.2.1 Plug-in Interfaces 


The following table describes the interfaces that plug-in developers must implement. 


Framework Storage Message Plug-in (msg_plugin) 
(framework_plugin) 
Message Filter Msg_Plugin_Filter_Interface.h 
Message Transport Msg_Plugin_Transport_- 
Interface.h 
Storage, Message and Msg_Framework_Storage_- Msg_Plugin_Storage_- 
Account Interface.h Interface.h 
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7.2 Sequence Charts for the LiMo Messaging API 
The following sequence charts are provided: 
e Filter Plug-in: Set Filter List to Filter Messages 


Legend 


The chart below shows the legends used in the sequence charts. 


si 


nal ¿message 


function call 


function return 


callback 


Figure 7.4: Sequence Chart Legend 


Terms 
e MAPI: Messaging API 
e MsgFw: Messaging Framework 
+ TransportHandlerPlg: Transport Handler Plug-in 
e FwStoPlg: Framework Storage Plug-in 
e MsgStoPlg: Message Storage Plug-in 
e FilterPlg: Filter plug-in 
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7.3 Filter Plug-in: Set Filter List to Filter Messages 


Application MAPI Framework filterPlugin 
MsgSetFilterList© 


send the filter list to framework 


sks the filter list and oe it to the session. 
get the session list when message is da and check them one by one, sessions sorted by priority f 
get the filter list from session 


get each filter plugin capability, kii correct plugin for the filter id. 


aiaiai eds Check if the da satisfy the =a ‘uta rule. 
ita ie a If ME satisfies the filter rule, send the message to this sessi 


IF idad true, framwork stops eo other low io session.. 


| 


Figure 7.5: Filter Plug-in: Set Filter List to Filter Messages 
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